search

dotnet / format

Home for the dotnet-format command
MIT License
1.94k stars 173 forks source link

--include / --files documentation is confusing #634

Open pgrm opened 4 years ago

pgrm commented 4 years ago

When I run dotnet format --files .\src\ProjectFolder\Program.cs -v detailed I always see

  Formatting code files in workspace 'SOLUTION_FOLDER\Solution.sln'.
  Warnings were encountered while loading the workspace. Set the verbosity option to the 'diagnostic' level to log warnings.
  Formatted 0 of 321 files.
  Format complete in 5402ms.

I would have expected to see only one file formatted.

it works, when I run dotnet format --folder . --files .\src\ProjectFolder\Program.cs -v detailed (kudos to https://github.com/dotnet/format/issues/403)

But in the README it's described as dotnet format --include Programs.cs Utility\Logging.cs without further explanation (https://github.com/dotnet/format#how-to-use) - maybe it could be improved?

Background:

The reason I want to specify only specific files, is to run it as a pre-commit hook as quickly as possible.

jmarolf commented 4 years ago

I do think that most people assume that dotnet-format is only going to change their whitespace. There are lots of additional situations where it will need semantic information.

CC: @JoeRobich could we first look at the editorconfig files and only attempt to load a workspace if we find an option-set+command-line-args that require a workspace?

qubitz commented 4 years ago

If I'm reading between the lines correctly, in order to only look at the files specified with --files and prevent looking for a workspace (MSBuild project file or solution file), the --folder option is required because a workspace is searched for by default. Is this correct?

Also, the difference between --include and --files doesn't seem to be explained. Do they function the same way?

jmarolf commented 4 years ago

@qubitz you are correct.

By default running dotnet format will look for a solution/project file and attempt to formal all the *.cs files in that are included there. It can be thought of as the default is an implicit -w (the workspace option).

--include and --files are synonyms for the same option as you can see here: https://github.com/dotnet/format/blob/aed51cf8bba5dcddb5f1c9ee718ceca4e0603822/src/Program.cs#L37

pgrm commented 4 years ago

@jmarolf to be clear, I didn't mean, the behaviour should change, rather the documentation should reflect what is going on under the hood, maybe even explain why it's not always possible to just format the files without loading the whole workspace. Otherwise the user is left wondering what they did wrong.

JoeRobich commented 4 years ago

@pgrm Please let me know if this documentation is sufficient - https://github.com/dotnet/format/tree/master/docs#filter-files-to-format. If not, please recommend how it could be improved. Thanks!