# CSharpier CLI Commands

## Installation

### Local Tool (Recommended)

```bash
# Create tool manifest if missing
dotnet new tool-manifest

# Install CSharpier as local tool
dotnet tool install csharpier

# Update to latest version
dotnet tool update csharpier
```

### Global Tool

```bash
# Install globally
dotnet tool install -g csharpier

# Update globally
dotnet tool update -g csharpier
```

## Formatting Commands

### Format Files

```bash
# Format all files in current directory recursively
dotnet csharpier .

# Format specific file
dotnet csharpier MyFile.cs

# Format specific directory
dotnet csharpier src/

# Format multiple paths
dotnet csharpier src/ tests/
```

### Check Mode (CI)

```bash
# Check formatting without modifying files
# Returns non-zero exit code if files need formatting
dotnet csharpier check .

# Check specific directory
dotnet csharpier check src/
```

### Additional Options

```bash
# Write formatted files to stdout instead of modifying
dotnet csharpier --write-stdout MyFile.cs

# Skip write (dry run) - validates syntax without output
dotnet csharpier --skip-write .

# Include generated files (excluded by default)
dotnet csharpier --include-generated .

# Disable cache (useful for debugging)
dotnet csharpier --no-cache .

# Use fast exit on first error
dotnet csharpier --fast .

# Pipe content through stdin/stdout
cat MyFile.cs | dotnet csharpier --write-stdout
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success - all files formatted or already formatted |
| 1 | Error - formatting failed or files need formatting (check mode) |

## CI Integration Examples

### GitHub Actions

```yaml
- name: Check formatting
  run: dotnet csharpier check .
```

### Azure DevOps

```yaml
- script: dotnet csharpier check .
  displayName: 'Check CSharpier formatting'
```

### Pre-commit Hook

```bash
#!/bin/sh
dotnet csharpier check .
```

## MsBuild Integration

Add to `.csproj` for build-time formatting check:

```xml
<Target Name="CheckFormatting" BeforeTargets="Build">
  <Exec Command="dotnet csharpier check ." />
</Target>
```

## IDE Extensions

- **Visual Studio**: CSharpier extension from VS Marketplace
- **VS Code**: CSharpier extension
- **JetBrains Rider**: CSharpier plugin

Configure format-on-save in IDE settings for seamless workflow.

# CSharpier Configuration

## Configuration File

CSharpier uses `.csharpierrc` (or `.csharpierrc.json`, `.csharpierrc.yaml`) in the repository root.

### JSON Format (.csharpierrc or .csharpierrc.json)

```json
{
  "printWidth": 100,
  "useTabs": false,
  "tabWidth": 4,
  "endOfLine": "auto"
}
```

### YAML Format (.csharpierrc.yaml)

```yaml
printWidth: 100
useTabs: false
tabWidth: 4
endOfLine: auto
```

## Configuration Options

### printWidth

Maximum line width before wrapping.

- **Type**: integer
- **Default**: 100
- **Range**: 1-1000

```json
{
  "printWidth": 120
}
```

### useTabs

Use tabs instead of spaces for indentation.

- **Type**: boolean
- **Default**: false

```json
{
  "useTabs": true
}
```

### tabWidth

Number of spaces per indentation level (when `useTabs` is false).

- **Type**: integer
- **Default**: 4
- **Range**: 1-1000

```json
{
  "tabWidth": 2
}
```

### endOfLine

Line ending style.

- **Type**: string
- **Default**: "auto"
- **Values**: "auto", "lf", "crlf"

```json
{
  "endOfLine": "lf"
}
```

| Value | Description |
|-------|-------------|
| auto | Use existing line endings (mixed files use first line's ending) |
| lf | Unix-style line endings (`\n`) |
| crlf | Windows-style line endings (`\r\n`) |

## Ignore File

Create `.csharpierignore` in the repository root to exclude files from formatting.

### Syntax

Uses gitignore-style patterns:

```gitignore
# Ignore generated files
**/Generated/**
**/*.generated.cs

# Ignore specific directories
**/obj/
**/bin/
**/Migrations/

# Ignore specific files
src/Legacy/OldCode.cs

# Ignore test fixtures
tests/Fixtures/**/*.cs
```

### Default Exclusions

CSharpier automatically excludes:

- Files in `obj/` and `bin/` directories
- Files matching `*.generated.cs` pattern
- Files with `<auto-generated>` comment header

## EditorConfig Integration

CSharpier respects `.editorconfig` for some settings:

```ini
[*.cs]
indent_style = space
indent_size = 4
end_of_line = lf
max_line_length = 100
```

Priority order:

1. `.csharpierrc` settings (highest)
2. `.editorconfig` settings
3. CSharpier defaults (lowest)

## Preprocessor Directives

CSharpier handles preprocessor directives but may format them differently than expected. Use `.csharpierignore` for files with complex preprocessor logic that must not change.

## Example Repository Setup

```text
repo/
├── .csharpierrc
├── .csharpierignore
├── .editorconfig
├── .config/
│   └── dotnet-tools.json
└── src/
    └── ...
```

### Minimal .csharpierrc

```json
{
  "printWidth": 100
}
```

### Minimal .csharpierignore

```gitignore
**/Migrations/
**/Generated/
```

## Troubleshooting

### Formatting Conflicts with dotnet format

If using both tools, ensure they do not conflict:

1. Disable whitespace/formatting rules in `.editorconfig` for `dotnet format`
2. Let CSharpier own all formatting decisions
3. Document ownership in `AGENTS.md`

### Cache Issues

Clear the CSharpier cache if formatting seems inconsistent:

```bash
# Disable cache for single run
dotnet csharpier --no-cache .

# Cache location (for manual clearing)
# Windows: %LOCALAPPDATA%/CSharpier
# macOS/Linux: ~/.cache/CSharpier
```

# CSharpier

## Open/Free Status

- open source
- free to use

## Install

Global tool:

```bash
dotnet tool install csharpier -g
```

## Verify First

Before installing, check whether the repo already has a local or global CSharpier tool:

```bash
rg --files -g '.config/dotnet-tools.json' -g '.csharpierignore'
dotnet tool list --local
dotnet tool list --global
command -v csharpier
```

## Common Usage

```bash
csharpier format .
csharpier check .
dotnet csharpier --version
```

## CI Fit

- use `csharpier check .` as the gate
- keep `.csharpierignore` versioned if needed
- document the relationship to `.editorconfig` and `dotnet format`

## When Not To Use

- when the repo wants detailed `.editorconfig`-driven formatting rather than one opinionated formatter

## Sources

- [CSharpier repository](https://github.com/belav/csharpier)