dotnet-format.md

dotnet format commands

Note: implicit in this doc is that we keep the name format as the root command.

Whitespace

Command Format: dotnet format <workspace> --fix-whitespace

Fixes whitespace only. Just looks at files and folders

Alias: 'w'. Invoking dotnet format without any arguments is equivalent to doing dotnet format --fix-whitespace

Arguments:

• workspace (Optional): a folder or file (must exist). If the path evaluated to either a sln file or a csproj file we will attempt to laod it to determine the set of files to format. If the path evaluated to a folder or is not specified dotnet format uses the directory it was invoked from and just recurses through the files in that directory.

Code Style

Command Format: dotnet format <workspace> --fix-style <severity>

Only fixes code style (aka code cleanup). Loads your solution or project.

Alias: 's'

Arguments:

• workspace (Optional): a path that contains a solution or project. so C:\workspace is a valid workspace if it has either C:\workspace\*.sln or C:\workspace\*.csproj. This mirrors the behavior for dotnet build i.e. if dotnet build works for a path then dotnet format --fix-style should also work. If not specified dotnet format uses the directory it was invoked from.

• severity (Optional): the severity of the code style options to fix. By default it is info to ensure it fixes everything that is specified in your editorconfig file. Possible values are info, warning, and error.

Analyzers

Command Format: dotnet format <workspace> --fix-analyzers <severity>

Alias: 'a'

Arguments:

• workspace (Optional): evaluated identically to how it is for --fix-style. If not specified dotnet format uses the directory it was invoked from.

Fixing everything

Command Format: dotnet format <workspace> --fix-all <severity>

Alias: no alias for this command. passing -wsa will do the same thing.

Arguments:

• workspace (Optional): evaluated identically to how it is for --fix-style

• severity (Optional): the severities passed into both the --fix-style and --fix-analyzers commands.

@jmarolf I like that you kept --fix-. Previously, we had talked about whether it was redundant. I think this will be a good bridge to it being incorporated into the CLI, especially if they introduce a Fix command for style and analyzers.

Whitespace

Fixes whitespace only. Just looks at files and folders

Are you saying that if the <workspace> is folder that we do not search for a solution or project? Are you saying that there is no longer a --folder option?

I believe if the user has specified a solution or project it should be used as the workspace. There are repos with test assets that are not part of solutions today, which would be discovered and formatted when treating the path as folder of code files.

Fixing everything

passing -wsa will do the same thing.

The benefit this option has over -wsa is that the would apply to both CodeStyle and Analyzer options. Whereas, with -wsa, I believe it applies to only the last specified.

Are you saying that there is no longer a --folder option?

That is what I am saying, but the example you bring up about test assets is a good one. My argument is that editorconfig is all about folders. I would like that folder-based view to be how folks think about things instead of however msbuild chooses to include things (maybe that is a bad idea). Basically my proposal for the person that doesn't want to format their test code is to add an editorconfig to that folder telling us to ignore it (I believe the generated code option will do that today/eventually?).

As a compromise can we say that the default for whitespace is to use the folder mode but if a user explicitly passes in a project or solution file we will switch to using that?

The benefit this option has over -wsa is that the would apply to both CodeStyle and Analyzer options. Whereas, with -wsa, I believe it applies to only the last specified.

yeah, good point. You have no way to change the severity with the posix style commands.

As a compromise can we say that the default for whitespace is to use the folder mode but if a user explicitly passes in a project or solution file we will switch to using that?

I am onboard with this proposal.

alright, I'll update the gist

I will also note that I think --exclude is another solution here. It seems like we have several mechanisms to include/exclude files as the user wants. I am still on the fence as the whether we really want a --folder option.

@jmarlof I think removing the --folder option is fine. --fix-whitespace (or the default behavior) will automatically treat folder path workspaces as folders of files.