Format: Automated Code Formatter

This projects implements an opinionated, non-configurable enforcer of code style. The aim is to take control of source formatting away from the developer, reducing cognitive load and allowing you to focus on what matters.

Features

☑️ Consistent code styling of C/C++, Python, Java, SQL, JavaScript, HTML, Protocol Buffers, CSS, Go, Markdown, plain text, and JSON files.

☑️ Git-aware pre-commit mode which formats changed files and signs off commits.

☑️ Fast incremental formats of large code bases using a "last modified" time stamp cache.

☑️ Black-listing of files from automated formatting using git-like ignore files.

☑️ Safe execution using inter-process locking to prevent multiple formatters modifying files simultaneously.

Install

Download an archive from the release page and extract it in your $PATH.

Requires Python >= 3.7 and sqlite. Syntax-specific formatters may have additional dependencies:

• Java files require a host java.
• JSON files require jsonlint.

Usage

Format files in-place using:

$ format <path ...>

If a path is a directory, all files inside it are formatted. The type of formatting applied to a file is determined by its suffix. To print the files that will be formatted without changing them, use:

$ format --dry_run <path ...>

Use the --watch flag on linux (sorry, no macOS support as of yet) to watch files or directories and run the formatter on them on change:

$ format --watch <path ...>

For git repositories, you can install the formatter to execute as a pre-commit hook using:

$ format --install_pre_commit_hook

This installs hooks that run the formatter on changelists before commits, and adds a "Signed-off-by" footer to commit messages verifying that the commit contents passed formatting checks.

If you want to exclude files from formatting, create a .formatignore file. It has similar rules to .gitignore files, e.g.:

$ cat .formatignore
# Everything after '#' character is a comment
hello.txt  # Name specific files to exclude from formatting
**/*.json  # Or glob them
!package.json  # Use '!' character to create un-ignore patterns

This program uses a filesystem cache to store various attributes such as a database of file modified times. See format --print_cache_path to print the path of the cache.

Development

Development takes place in the phd repository. Grab a copy from here:

$ git clone https://github.com/ChrisCummins/phd.git format
$ cd format

Run the test suite using:

$ bazel test //tools/format/...

Build and install the formatter binary from source using:

$ ./tools/format/install.sh

Update the format repository using:

$ bazel run //tools/format:export

Then manually create a new release and attach binary files.

License

Copyright 2020 Chris Cummins [email protected].

Released under the terms of the Apache 2.0 license. See LICENSE for details.