--include / --files documentation is confusing

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.

[JoeRobich]

@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!

[jmarolf]

@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