Audit command line options

[nrc]

Should they all be there? Which should be considered stable vs unstable? Are the arguments the best they should be? Are we missing any?

[nrc]

Rustfmt options:

usage: target/debug/rustfmt [options] <file>...

Options:
        --color [always|never|auto]
                        Use colored output (if supported)
        --config-help   Show details of rustfmt configuration options
        --config-path [Path for the configuration file]
                        Recursively searches the given path for the
                        rustfmt.toml config file. If not found reverts to the
                        input file path
        --dump-default-config [PATH]
                        Dumps default configuration to PATH. PATH defaults to
                        stdout, if omitted.
        --dump-minimal-config PATH
                        Dumps configuration options that were checked during
                        formatting to a file.
        --error-on-unformatted
                        Error if unable to get comments or string literals
                        within max_width, or they are left with trailing
                        whitespaces
        --file-lines JSON
                        Format specified line ranges. See README for more
                        detail on the JSON format.
    -h, --help          Show this message
        --skip-children
                        Don't reformat child modules
        --unstable-features
                        Enables unstable features. Only available on nightly
                        channel
    -v, --verbose       Print verbose output
    -V, --version       Show version information
        --write-mode [replace|overwrite|display|plain|diff|coverage|checkstyle]
                        How to write output (not usable when piping from
                        stdin)

cargo fmt options:

usage: cargo fmt [options]

Options:
    -h, --help          show this message
    -q, --quiet         no output printed to stdout
    -v, --verbose       use verbose output
    -p, --package <package>
                        specify package to format (only usable in workspaces)
        --version       print rustfmt version and exit
        --all           format all packages (only usable in workspaces)

This utility formats all bin and lib files of the current crate using rustfmt. Arguments after `--` are passed to rustfmt.

[nrc]

Looking at cargo fmt first.

I think having a minimal set of Cargo-like options and then using -- for the Rustfmt options is a good strategy. Under that model, my only query is whether we should support --version, since -- -V would work and be less confusing with cargo --version.

An alternative would be to support Rustfmt options without the --. cargo build, for example, supports a lot more options and does so directly, however, cargo rustc supports the -- for passing arguments to rustc. I guess it depends whether we think the mental model should be that cargo fmt is a thing or a shim around rustfmt.

[nrc]

We don't currently have unstable command line options, but I think we should and I think the following should be unstable: --file-lines and --dump-minimal-config, and write modes plain|diff|coverage|checkstyle. I am unsure about --dump-default-config - it seems useful, but I'm not sure about any back compat hazard from using the generated config or if it takes account of unstable features, etc.

Otherwise I think the command line flags looks good. I think for both binaries, we should consider the ordering of the flags in the help message.

[nrc]

And just to be really organised, a TODO list:

• implement unstable command line flags
• check the correct flags and write modes are unstable
• check ordering of flags in help messages (and that unstable ones are only shown as appropriate)
• decide on -- for cargo fmt
• decide on --version for cargo fmt
• replace write mode with flags, see Redesign CLI #1028

[nrc]

Proposal for a new CLI, inspired by #1028. The help messages need some work,

OPTIONS:
    --check
                               Check if formatting is correct, emit diff if not
    --emit [files|stdout|checkstyle|coverage]
                               What to emit
    --backup
                               Backup any files which are changed
    --color [always|never|auto]
                               Use colored output (if supported)
    --config-path [PATH]
                               Recursively searches the given path for the
                               rustfmt.toml config file. If not found reverts to the
                               input file path
    --print-config [minimal|default] [PATH]
                               Dumps default or minimal configuration to PATH. PATH defaults to
                               stdout, if omitted. A minimal config is the options checked
                               during formatting.
    --file-lines JSON
                               Format specified line ranges. See `--help file-lines` for details
    --unstable-features
                               Enables unstable features. Only available on nightly
                               channel
    -v, --verbose              Print verbose output
    --quiet                    Emit less info
    -h, --help [topic]         Prints help information
                               Displays detailed help for TOPIC [values: config, file-lines]
    -V, --version              Prints version information

Questions:

• --print-config or --print
• --error-on-unformatted - do we need it? Feels like a debugging option (and can be used via config file)
• --skip-children - feels like it is better used via a config file (or API)
• do we need --emit diff? --check basically does this
• what should be unstable?

[nrc]

We could remove --emit files since that is the default behaviour.

[CAD97]

On --error-on-unformatted:

In order to check formatting on CI, there needs to be an option that returns a failing error code when the source is not formatted. If this is how --check behaves, then --error-on-unformatted would indeed be redundant.

[nrc]

That's not quite the semantics of --error-on-unformatted. For example, consider a program which has a comment which is 101 chars long, --check would return 0 for that because rustfmt would not format it any differently, however, --error-on-unformatted would return 1 because it exceeds the maximum width (it might want a better name).

[ssokolow]

We could remove --emit files since that is the default behaviour.

It's generally considered good practice to support defaults as options in case someone wants to incorporate a tool into a frontend or automation harness, so they can just specify --emit {} rather than needing a special branch just to omit the --emit entirely if the default is chosen.

Ideally, you also support multiple copies of the same option in a "last one wins" configuration so it's possible for things like the alias shell built-in to handle custom defaults simply by appending arguments to a pre-specified list of them. In that case, you need --emit files as a means to undo a previous user default.

[jonhoo]

Worth pointing out that this breaks rust.vim: rust-lang/rust.vim#212