Freshen up the documentation.

- Update the invocation examples to use subcommands instead of the `-m/--mode` flag; add the `--strict`, `--assume-filename`, `--ignore-unparsable-files`, and `--(no-)color-diagnostics` flags. - Mention the release tags in the version table, and use those in the `git checkout` command instead of the branch names.
apple · Nov 15, 2021 · 8d69a07 · 8d69a07
1 parent e23f8eb
commit 8d69a07
Show file tree

Hide file tree

Showing 2 changed files with 137 additions and 52 deletions.
diff --git a/Documentation/Configuration.md b/Documentation/Configuration.md
@@ -113,6 +113,6 @@ behave when acting upon source code or syntax trees.
 
 The default initializer for `Configuration` creates a value equivalent to the
 default configuration that would be printed by invoking
-`swift-format --mode dump-configuration`. API users can also provide their own
+`swift-format dump-configuration`. API users can also provide their own
 configuration by modifying this value or loading it from another source using
 Swift's `Codable` APIs.
diff --git a/README.md b/README.md
@@ -17,81 +17,156 @@ invoked via an [API](#api-usage).
 
 `swift-format` depends on [SwiftSyntax](https://github.com/apple/swift-syntax)
 and the standalone parsing library that is distributed as part of the Swift
-toolchain. The SwiftSyntax version in use must match the toolchain version, so
-you should check out and build `swift-format` from the branch that is
-compatible with the version of Swift you are using. This version dependency
-is also expressed in the `SwiftSyntax` dependency in
-[Package.swift](Package.swift).
-
-| Xcode Release | Swift Version                           | `swift-format` Branch |
-|:-------------:|:---------------------------------------:|:----------------------|
-| –             | Swift at `main`                         | `main`                |
-| Xcode 13.0    | Swift 5.5                               | `swift-5.5-branch`    |
-| Xcode 12.5    | Swift 5.4                               | `swift-5.4-branch`    |
-| Xcode 12.0    | Swift 5.3                               | `swift-5.3-branch`    |
-| Xcode 11.4    | Swift 5.2                               | `swift-5.2-branch`    |
-| Xcode 11.0    | Swift 5.1                               | `swift-5.1-branch`    |
-
-For example, if you are using Xcode 12.0 (Swift 5.3), you can check out and
-build `swift-format` using the following commands:
-
-```
-git clone -b swift-5.3-branch https://github.com/apple/swift-format.git
+toolchain, so you should check out and build `swift-format` from the release
+tag or branch that is compatible with the version of Swift you are using.
+
+The major and minor version components of `swift-format` and SwiftSyntax must
+be the same—this is expressed in the `SwiftSyntax` dependency in
+[Package.swift](Package.swift)—and those version components must match the
+Swift toolchain that is installed and used to build and run the formatter:
+
+| Xcode Release   | Swift Version          | `swift-format` Branch / Tags     |
+|:----------------|:-----------------------|:---------------------------------|
+| –               | Swift at `main`        | `main`                           |
+| Xcode 13.0–13.2 | Swift 5.5              | `swift-5.5-branch` / `0.50500.x` |
+| Xcode 12.5      | Swift 5.4              | `swift-5.4-branch` / `0.50400.x` |
+| Xcode 12.0–12.4 | Swift 5.3              | `swift-5.3-branch` / `0.50300.x` |
+| Xcode 11.4–11.7 | Swift 5.2              | `swift-5.2-branch` / `0.50200.x` |
+| Xcode 11.0–11.3 | Swift 5.1              | `swift-5.1-branch`               |
+
+For example, if you are using Xcode 13.1 (Swift 5.5), you will need
+`swift-format` 0.50500.0.
+
+## Getting swift-format
+
+If you are mainly interested in using swift-format (rather than developing it),
+then once you have identified the version you need, you can check out the
+source and build it using the following commands:
+
+```sh
+VERSION=0.50500.0  # replace this with the version you need
+git clone https://github.com/apple/swift-format.git
 cd swift-format
-swift build
+git checkout "tags/$VERSION"
+swift build -c release
 ```
 
-You can also add the `--single-branch` option if you only want to clone that
-specific branch.
+Note that the `git checkout` command above will leave the repository in a
+"detached HEAD" state. This is fine if building and running the tool is all you
+want to do.
 
-The `main` branch is used for development and may depend on either a release
-version of Swift or on a developer snapshot. Changes committed to `main`
-that are compatible with the latest release branch will be cherry-picked into
-that branch.
+Once the build has finished, the `swift-format` executable will be located at
+`.build/release/swift-format`.
 
 To test that the formatter was built succesfully and is compatible with your
-Swift toolchain, you can run the following command:
+Swift toolchain, you can also run the following command:
 
-```
+```sh
 swift test --parallel
 ```
+
 We recommend using the `--parallel` flag to speed up the test run since there
 are a large number of tests.
 
 ## Command Line Usage
 
+The general invocation syntax for `swift-format` is as follows:
+
+```sh
+swift-format [SUBCOMMAND] [OPTIONS...] [FILES...]
+```
+
+The tool supports a number of subcommands, each of which has its own options
+and are described below. Descriptions of the subcommands that are available
+can also be obtained by running `swift-format --help`, and the description of
+a specific subcommand can be obtained by using the `--help` flag after the
+subcommand name; for example, `swift-format lint --help`.
+
+### Formatting
+
+```sh
+swift-format [format] [OPTIONS...] [FILES...]
 ```
-swift-format [OPTIONS] FILE...
+
+The `format` subcommand formats one or more Swift source files (or source code
+from standard input if no file paths are given on the command line). Writing
+out the `format` subcommand is optional; it is the default behavior if no other
+subcommand is given.
+
+This subcommand supports all of the
+[common lint and format options](#options-supported-by-formatting-and-linting),
+as well as the formatting-only options below:
+
+*   `-i/--in-place`: Overwrites the input files when formatting instead of
+    printing the results to standard output. _No backup of the original file is
+    made before it is overwritten._
+
+### Linting
+
+```sh
+swift-format lint [OPTIONS...] [FILES...]
 ```
 
-The `swift-format` tool can be invoked with one or more `.swift` source files,
-as well as the following command line options:
+The `lint` subcommand checks one or more Swift source files (or source code
+from standard input if no file paths are given on the command line) for style
+violations and prints diagnostics to standard error for any violations that
+are detected.
+
+This subcommand supports all of the
+[common lint and format options](#options-supported-by-formatting-and-linting),
+as well as the linting-only options below:
+
+*   `-s/--strict`: If this option is specified, lint warnings will cause the
+    tool to exit with a non-zero exit code (failure). By default, lint warnings
+    do not prevent a successful exit; only fatal errors (for example, trying to
+    lint a file that does not exist) cause the tool to exit unsuccessfully.
+
+### Options Supported by Formatting and Linting
+
+The following options are supported by both the `format` and `lint`
+subcommands:
 
-* `-v/--version`: Prints the `swift-format` version and exits.
+*   `--assume-filename <path>`: The file path that should be used in
+    diagnostics when linting or formatting from standard input. If this option
+    is not provided, then `<stdin>` will be used as the filename printed in
+    diagnostics.
 
-* `-m/--mode <format|lint|dump-configuration>`: The mode in which to run
-  `swift-format`. The `format` mode formats source files. The `lint` mode
-  only prints diagnostics indicating style violations. The `dump-configuration`
-  mode dumps the default `swift-format` configuration to standard output.
+*   `--color-diagnostics/--no-color-diagnostics`: By default, `swift-format`
+    will print diagnostics in color if standard error is connected to a
+    terminal and without color otherwise (for example, if standard error is
+    being redirected to a file). These flags can be used to force colors on
+    or off respectively, regardless of whether the output is going to a
+    terminal.
 
-  If unspecified, the default mode is `format`.
+*   `--configuration <file>`: The path to a JSON file that contains
+    [configurable settings](#configuring-the-command-line-tool) for
+    `swift-format`. If omitted, a default configuration is use (which
+    can be seen by running `swift-format dump-configuration`).
 
-* `--configuration <file>`: The path to a JSON file that contains
-  [configurable settings](#configuration) for `swift-format`. If omitted, a
-  default configuration is use (which can be seen by running
-  `--mode dump-configuration`).
+*   `--ignore-unparsable-files`: If this option is specified and a source file
+    contains syntax errors or can otherwise not be parsed successfully by the
+    Swift syntax parser, it will be ignored (no diagnostics will be emitted
+    and it will not be formatted). Without this option, an error will be
+    emitted for any unparsable files.
 
-* `-i/--in-place`: Overwrites the input files when formatting instead of
-  printing the results to standard output.
+*   `-p/--parallel`: Process files in parallel, simultaneously across
+    multiple cores.
 
-* `-p/--parallel`: Process files in parallel, simultaneously across
-  multiple cores.
+*   `-r/--recursive`: If specified, then the tool will process `.swift` source
+    files in any directories listed on the command line and their descendants.
+    Without this flag, it is an error to list a directory on the command line.
 
-* `-r/--recursive`: If specified, then the tool will process `.swift` source
-  files in any directories listed on the command line and their descendants.
-  Without this flag, it is an error to list a directory on the command line.
+### Viewing the Default Configuration
 
-### Configuration
+```sh
+swift-format dump-configuration
+```
+
+The `dump-configuration` subcommand dumps the default configuration in JSON
+format to standard output. This can be used to simplify generating a custom
+configuration, by redirecting it to a file and editing it.
+
+### Configuring the Command Line Tool
 
 For any source file being checked or formatted, `swift-format` looks for a
 JSON-formatted file named `.swift-format` in the same directory. If one is
@@ -111,6 +186,11 @@ See [Documentation/Configuration.md](Documentation/Configuration.md) for a
 description of the configuration file format and the settings that are
 available.
 
+### Miscellaneous
+
+Running `swift-format -v` or `swift-format --version` will print version
+information about `swift-format` version and then exit.
+
 ## API Usage
 
 `swift-format` can be easily integrated into other tools written in Swift.
@@ -133,7 +213,12 @@ Please see the documentation in the
 [`SwiftLinter`](Sources/SwiftFormat/SwiftLinter.swift) classes for more
 information about their usage.
 
-## Development
+### Checking Out the Source Code for Development
+
+The `main` branch is used for development. Pull requests should be created
+to merge into the `main` branch; changes that are low-risk and compatible with
+the latest release branch may be cherry-picked into that branch after they have
+been merged into `main`.
 
 If you are interested in developing `swift-format`, there is additional
 documentation about that [here](Documentation/Development.md).