Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dotnet/format
Home for the dotnet-format command
https://github.com/dotnet/format
Last synced: about 2 months ago
JSON representation
Home for the dotnet-format command
- Host: GitHub
- URL: https://github.com/dotnet/format
- Owner: dotnet
- License: mit
- Created: 2019-02-15T23:46:51.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-11T12:48:23.000Z (about 2 months ago)
- Last Synced: 2024-04-12T00:50:58.238Z (about 2 months ago)
- Language: C#
- Size: 4.19 MB
- Stars: 1,892
- Watchers: 43
- Forks: 170
- Open Issues: 197
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.TXT
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: docs/Supported-.editorconfig-options.md
Lists
- static-analysis - dotenet-format - format is able to format C# and Visual Basic projects with a subset of supported `.editorconfig` options. (Multiple languages)
- awesome - dotnet/format - Home for the dotnet-format command (C\#)
- khulnasoft-labs_awesome-linter - dotnet-format - format](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) | (Supported Linters)
- awesome-stars - format - format command | dotnet | 1911 | (C#)
README
## dotnet-format
|Branch| Windows (Debug)| Windows (Release)| Linux (Debug) | Linux (Release) | Localization (Debug) | Localization (Release) |
|---|:--:|:--:|:--:|:--:|:--:|:--:|
[main](https://github.com/dotnet/format/tree/main)|[](https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=176&branchName=main)|[](https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=176&branchName=main)|[](https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=176&branchName=main)|[](https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=176&branchName=main)|[](https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=176&branchName=main)|[](https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=176&branchName=main)|
`dotnet-format` is a code formatter for `dotnet` that applies style preferences to a project or solution. Preferences will be read from an `.editorconfig` file, if present, otherwise a default set of preferences will be used. At this time `dotnet-format` is able to format C# and Visual Basic projects with a subset of [supported .editorconfig options](./docs/Supported-.editorconfig-options.md).
### How To Use
dotnet-format is now part of the .NET 6 SDK. Invoking the `dotnet format` command will fix whitespace, code style, and analyzer issues by default. dotnet-format will look in the current directory for a project or solution file and use that as the workspace to format. If more than one project or solution file is present in the current directory, you will need to specify the workspace to format. You can control how verbose the output will be by using the `--verbosity` option.
There are also 3 subcommands to target specific scenarios:
- `dotnet format whitespace`: fixes whitespace
- `dotnet format style`: runs code style analyzers
- `dotnet format analyzers`: runs third party analyzers
#### Common options for all commands
- `--no-restore`: Doesn't execute an implicit restore before formatting.
- `--include-generated`: Format files generated by the SDK
- `--include`: A space-separated list of relative file or folder paths to include in formatting. All files are formatted if empty. (e.g. `--include path/to/file.cs path/to/folder folder2/*.vb`)
- `--exclude`: A space-separated list of relative file or folder paths to exclude from formatting. (e.g. `--exclude path/to/file.cs path/to/folder folder2/*.vb`)
- `--verbosity`: Set the verbosity level. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]
- `--report`: Accepts a file path, which if provided, will produce a json report in the given directory.
- `--binarylog`: Log all project or solution load information to a binary log file.
- `--verify-no-changes`: Verify no formatting changes would be performed. Terminates with a non-zero exit code if any files would have been formatted.
#### Unique options for `dotnet format`
- `--diagnostics`: A space separated list of diagnostic ids to use as a filter when fixing code style or 3rd party issues.
- `--severity`: The severity of diagnostics to fix. Allowed values are info, warn, and error.
Note: if the user specifies a severity here it is used for both style and analyzers.
#### Unique options for `dotnet format whitespace`
- `--folder`: Whether to treat the workspace argument as a simple folder of files.
#### Unique options for `dotnet format style`
- `--diagnostics`: A space separated list of diagnostic ids to use as a filter when fixing code style or 3rd party issues.
- `--severity`: The severity of diagnostics to fix. Allowed values are info, warn, and error.
#### Unique options for `dotnet format analyzers`
- `--diagnostics`: A space separated list of diagnostic ids to use as a filter when fixing code style or 3rd party issues.
- `--severity`: The severity of diagnostics to fix. Allowed values are info, warn, and error.
### Examples
Add `format` after `dotnet` and before the command arguments that you want to run:
| Examples | Description |
| ---------------------------------------------------------------- |--------------------------------------------------------------------------------------------------- |
| `dotnet format` | Formats and runs analysis for the project or solution in the current directory. |
| `dotnet format -v diag` | Formats and runs analysis with very verbose logging. |
| `dotnet format ` | Formats and runs analysis for a specific project or solution. |
| `dotnet format --severity error` | Formats, fixes codestyle errors, and fixes 3rd party analyzer errors. |
| `dotnet format whitespace --folder` | Formats a particular folder and subfolders. |
| `dotnet format style ` | Fixes only codestyle analyzer warnings. |
| `dotnet format style --severity error --no-restore` | Fixes only codestyle analyzer errors without performing an implicit restore. |
| `dotnet format style --diagnostics IDE0005` | Fixes only codestyle analyzer warnings for the IDE0005 diagnostic. |
| `dotnet format analyzers --severity error` | Fixes only 3rd party analyzer errors. |
| `dotnet format --include Program.cs Utility\Logging.cs` | Formats the files Program.cs and Utility\Logging.cs |
| `dotnet format --verify-no-changes` | Formats but does not save. Returns a non-zero exit code if any files would have been changed. |
| `dotnet format --report ` | Formats and saves a json report file to the given directory. |
| `dotnet format --include test/Utilities/*.cs --folder` | Formats the files expanded from native shell globbing (e.g. bash). Space-separated list of files are fed to formatter in this case. Also applies to `--exclude` option. |
| `dotnet format --include 'test/Utilities/*.cs' --folder` | With single quotes, formats the files expanded from built-in glob expansion. A single file pattern is fed to formatter, which gets expanded internally. Also applies to `--exclude` option. |
| `ls tests/Utilities/*.cs \| dotnet format --include - --folder` | Formats the list of files redirected from pipeline via standard input. Formatter will iterate over `Console.In` to read the list of files. Also applies to `--exclude` option. |
### How to install Development Builds
Development builds of `dotnet-format` are being hosted on Azure Packages.
Note: After installing .NET 6 Preview 7 SDK or higher you will need to run the dotnet-format global tool by invoking `dotnet-format`. Invoking `dotnet format` will invoke the SDK's copy of dotnet-format.
#### Installing the latest build
You can install the latest build of the tool using the following command.
```console
dotnet tool install -g dotnet-format --version "8.*" --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet8/nuget/v3/index.json
```
#### Installing a specific build
You can install a specific build of the tool using the following command. Be sure to update the version string to match the intended version.
```console
dotnet tool install -g dotnet-format --version "8.0.446201" --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet8/nuget/v3/index.json
```
You can visit the [dotnet8 feed](https://dev.azure.com/dnceng/public/_artifacts/feed/dotnet8/NuGet/dotnet-format/versions) for a full list of versions.
#### Looking for earlier versions of dotnet-format?
Visit the [dotnet7 feed](https://dev.azure.com/dnceng/public/_artifacts/feed/dotnet7/NuGet/dotnet-format/versions) or [dotnet6 feed](https://dev.azure.com/dnceng/public/_artifacts/feed/dotnet6/NuGet/dotnet-format/versions) instead. Be sure to use the source URL appropriate for the version that you are installing.
### How To Build From Source
You can build and package the tool using the following commands. The instructions assume that you are in the root of the repository.
```console
build -pack
# The final line from the build will read something like
# Successfully created package '..\artifacts\packages\Debug\Shipping\dotnet-format.8.0.0-dev.nupkg'.
# Use the value that is in the form `8.0.0-dev` as the version in the next command.
dotnet tool install --add-source .\artifacts\packages\Debug\Shipping -g dotnet-format --version
dotnet format
```
> Note: On macOS and Linux, `.\artifacts` will need be switched to `./artifacts` to accommodate for the different slash directions.
### How To Uninstall
You can uninstall the tool using the following command.
```console
dotnet tool uninstall -g dotnet-format
```