|
2 | 2 | CSharpier is an opinionated code formatter for c#. It uses Roslyn to parse your code and re-prints it using its own rules. The printing process was ported from [prettier](https://github.com/prettier/prettier) but has evolved over time. |
3 | 3 |
|
4 | 4 | ### Work In Progress |
5 | | -CSharpier is currently in alpha and I'd be hesitant to recommend using it on production code. |
6 | | - - It has been tested against a large number of public repositories to validate that the changes it makes do not lose any syntax but there is a possibility it will break your code. |
| 5 | +CSharpier is still in active development. |
| 6 | +- The rules it uses to format code are not yet finalized and some of the results are a little ugly. |
| 7 | +- The rules it uses to format your code will change over time. |
| 8 | +- It has been tested against a large number of public repositories to validate that the changes it makes do not lose any syntax but there is a possibility it will break your code. |
7 | 9 | - This process has been automated and runs each time code is pushed. |
8 | | - - The rules it uses to format code are not yet finalized and some of the results are ugly. |
9 | | - - The rules it uses to format your code will change over time. |
10 | | - - There are currently no options exposed for formatting. |
11 | | - - The options for what files it should format are limited. |
12 | | - - There have been a handful of critical bugs that resulted in a loss of source code since it has entered alpha. |
| 10 | + |
13 | 11 |
|
14 | 12 | I encourage you to try it out on your own code and report any bugs, code that doesn't format well, or opinions on how you think the formatting should change. If you can live with the fact that the formatting will be changing over time, it is reasonably safe to use. In addition to a steadily growing set of unit tests; csharpier is tested against ~60k c# files from a range of public repositories to validate it does not result in the lose of any source code. |
15 | 13 |
|
@@ -58,30 +56,74 @@ public class ClassName |
58 | 56 | dotnet tool install -g csharpier |
59 | 57 | ``` |
60 | 58 |
|
61 | | -## Usage |
62 | | -### Basic Usage |
| 59 | +## Basic Usage |
| 60 | +By default csharpier will validate any files it formats by comparing the resulting syntax tree to the original. |
| 61 | +Formatting will take longer, but csharpier will validate the formatted syntax tree against the original and warn if it believes it introduced breaking changes. |
| 62 | + |
63 | 63 | Run csharpier from the directory you wish to format. |
64 | 64 | ```console |
65 | | -# the first time running csharpier it is normally not possible to review all the changes it makes |
66 | | -# and catch any instances of code being lost |
67 | 65 | dotnet csharpier |
68 | | - |
69 | | -# after a project has already been csharpiered, you can choose |
70 | | -# to use the --fast flag to speed up formatting |
71 | | -dotnet csharpier --fast |
72 | 66 | ``` |
73 | 67 |
|
74 | | -### Formatting Single File |
75 | | -```console |
76 | | -dotnet chsarpier [PathToFile] |
| 68 | +## Configuration |
| 69 | +CSharpier has support for a configuration file. You can use any of the following files |
| 70 | +- A ```.csharpierrc``` file in JSON or YAML. |
| 71 | +- A ```.csharpierrc.json``` or ```.csharpierrc.yaml``` file. |
| 72 | + |
| 73 | +### Configuration Options |
| 74 | +JSON |
| 75 | +```json |
| 76 | +{ |
| 77 | + "printWidth": 100, |
| 78 | + "useTabs": false, |
| 79 | + "tabWidth": 4, |
| 80 | + "endOfLine": "lf" |
| 81 | +} |
| 82 | +``` |
| 83 | +YAML |
| 84 | +```json |
| 85 | +printWidth: 100 |
| 86 | +useTabs: false |
| 87 | +tabWidth: 4 |
| 88 | +endOfLine: lf |
77 | 89 | ``` |
78 | 90 |
|
79 | | -### More Information |
80 | | -CSharpier currently excludes .g.cs and .cshtml.cs files. |
| 91 | +#### Print Width |
| 92 | +Specify at what point the printer will wrap content. This is not a hard limit. Some lines will be shorter or longer. |
81 | 93 |
|
82 | | -By default csharpier will validate any files it formats by comparing the resulting syntax tree to the original. |
83 | | -Formatting will take longer, but csharpier will validate the formatted syntax tree against the original and warn if it believes it introduced breaking changes. |
| 94 | +Default 100 |
| 95 | +#### Use Tabs |
| 96 | +Indent lines with tabs instead of spaces. |
84 | 97 |
|
| 98 | +Default false |
| 99 | +#### Tab Width |
| 100 | +Specify the number of spaces used per indentation level. |
| 101 | + |
| 102 | +Default 4 |
| 103 | +#### End of Line |
| 104 | +Specify what type of line endings will be printed in files. |
| 105 | +Options |
| 106 | +- "lf" - Line feed only (\n) **Default** |
| 107 | +- "crlf" Carriage return and line feed (\r\n) |
| 108 | + |
| 109 | +### Ignoring Files |
| 110 | +Csharpier will ignore the following files |
| 111 | +- Any file that begins with ```TemporaryGeneratedFile_``` |
| 112 | +- Any file that ends with ```.designer.cs``` |
| 113 | +- Any file that ends with ```.generated.cs``` |
| 114 | +- Any file that ends with ```.g.cs``` |
| 115 | +- Any file that ends with ```.g.i.cs``` |
| 116 | +- Any file that begins with a comment that contains ```<autogenerated``` or ```<auto-generated``` |
| 117 | + |
| 118 | +Add a ```.csharpierignore``` file to ignore additional files and folders. The file uses [gitignore syntax](https://git-scm.com/docs/gitignore#_pattern_format) |
| 119 | + |
| 120 | +Example |
| 121 | +``` |
| 122 | +Uploads/ |
| 123 | +**/App_Data/*.cs |
| 124 | +``` |
| 125 | + |
| 126 | +### Command Line Options |
85 | 127 | ```console |
86 | 128 | Usage: |
87 | 129 | dotnet-csharpier [options] [<directoryOrFile>] |
@@ -149,6 +191,7 @@ An example of CSharpier finding a file that failed validation. |
149 | 191 |
|
150 | 192 | ## Contributing |
151 | 193 | See [Development Readme](CONTRIBUTING.md) |
152 | | -Join Us [](https://discord.gg/HfAKGEZQcX) |
153 | 194 |
|
| 195 | +Join Us [](https://discord.gg/HfAKGEZQcX) |
154 | 196 |
|
| 197 | +[ChangeLog](CHANGELOG.md) |
0 commit comments