README

!









Table of Contents
-----------------

- What?
- Why?
- How?
    - Command-line tool
    - Xcode source editor extension
    - Xcode build phase
    - Swift Package Manager plugin
    - Via Applescript
    - VSCode plugin
    - Sublime Text plugin
    - Nova plugin
    - Git pre-commit hook
    - GitHub Actions
    - On CI using Danger
    - Bazel build
    - Docker
    - Prerelease Builds
- Configuration
    - Options
    - Rules
    - Swift version
    - Config file
    - Globs
    - Linting
    - Error codes
    - Cache
    - Snapshot
    - File headers
    - Markdown formatting
- FAQ
- Known issues
- Tip Jar
- Credits


What is this?
----------------

SwiftFormat is a code library and command-line tool for reformatting Swift code on macOS, Linux or Windows.

SwiftFormat goes above and beyond what you might expect from a code formatter. In addition to adjusting white space it can insert or remove implicit self, remove redundant parentheses, and correct many other deviations from the standard Swift idioms.


Why would I want to do that?
-----------------------------

Many programmers have a preferred style for formatting their code, and others seem entirely blind to the existing formatting conventions of a project (to the enragement of their colleagues).

When collaborating on a project, it can be helpful to agree on a common coding style, but enforcing that manually is tedious and error-prone, and can lead to arguments if some participants take it more seriously than others.

Having a tool to automatically enforce a common style eliminates those issues, and lets you focus on the behavior of the code, not its presentation.


How do I install it?
---------------------

That depends - There are several ways you can use SwiftFormat:

1. As a command-line tool that you run manually, or as part of some other toolchain
2. As a Source Editor Extension that you can invoke via the Editor  SwiftFormat menu within Xcode
3. As a build phase in your Xcode project, so that it runs every time you press Cmd-R or Cmd-B, or
4. As a Git pre-commit hook, so that it runs on any files you've changed before you check them in


Command-line tool
-------------------

Installation:

You can install the swiftformat command-line tool on macOS or Linux using Homebrew. Assuming you already have Homebrew installed, just type:

bash
$ brew install swiftformat


To update to the latest version once installed:

bash
$ brew upgrade swiftformat


Alternatively, you can install the tool on macOS or Linux by using Mint as follows:

bash
$ mint install nicklockwood/SwiftFormat


If you use Nix, you can add SwiftFormat to a devShell using nixpkgs:

nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  };

  outputs = { nixpkgs, ... }:
    let
      system = "aarch64-darwin";
      pkgs = import nixpkgs { inherit system; };
    in {
      devShells.${system}.default = pkgs.mkShell {
        packages = [
          pkgs.swiftformat
        ];
      };