git-format-staged

git-format-staged

Consider a project where you want all code formatted consistently. So you use a formatting command. (For example I use prettier in my Javascript and Typescript projects.) You want to make sure that everyone working on the project runs the formatter, so you use a tool like husky to install a git pre-commit hook. The naive way to write that hook would be to:

• get a list of staged files
• run the formatter on those files
• run git add to stage the results of formatting

The problem with that solution is it forces you to commit entire files. At worst this will lead to contributors to unwittingly committing changes. At best it disrupts workflow for contributors who use git add -p.

git-format-staged tackles this problem by running the formatter on the staged version of the file. Staging changes to a file actually produces a new file that exists in the git object database. git-format-staged uses some git plumbing commands to send content from that file to your formatter. The command replaces file content in the git index. The process bypasses the working tree, so any unstaged changes are ignored by the formatter, and remain unstaged.

After formatting a staged file git-format-staged computes a patch which it attempts to apply to the working tree file to keep the working tree in sync with staged changes. If patching fails you will see a warning message. The version of the file that is committed will be formatted properly - the warning just means that working tree copy of the file has been left unformatted. The patch step can be disabled with the --no-update-working-tree option.

How to install

Install with Nix

Install via the CLI:

$ nix profile install github:hallettj/git-format-staged

Or add to your flake imports, and use the default package output.

Install with NPM

Requires Python 3.8 or later.

Install as a development dependency in a project that uses npm packages:

$ npm install --save-dev git-format-staged

Or install globally:

$ npm install --global git-format-staged

Or just copy the script

Requires Python 3.8 or later.

If you do not use the above methods you can copy the git-format-staged script from this repository and place it in your executable path. The script is MIT-licensed - so you can check the script into version control in your own open source project if you wish.

How to use

For detailed information run:

$ git-format-staged --help

The command expects a shell command to run a formatter, and one or more file patterns to identify which files should be formatted. For example:

$ git-format-staged --formatter 'prettier --stdin-filepath {}' 'src/*.js'

That will format all files under src/ and its subdirectories using prettier. The file pattern is tested against staged files using Python's fnmatch function: each * will match nested directories in addition to file names.

The formatter command must read file content from stdin, and output formatted content to stdout.

Note that the syntax of the fnmatch glob match is a is a bit different from normal shell globbing. So if you need to match multiple patterns, you should pass multiple arguments with different patterns, and they will be grouped. So instead of e.g. 'src/**/*.{js,jsx,ts}', you would use:

$ git-format-staged --formatter 'prettier --stdin-filepath {}' 'src/*.js' 'src/*.jsx' 'src/*.ts'

Files can be excluded by prefixing a pattern with !. For example:

$ git-format-staged --formatter 'prettier --stdin-filepath {}' '*.js' '!flow-typed/*'

Patterns are evaluated from left-to-right: if a file matches multiple patterns the right-most pattern determines whether the file is included or excluded.

git-format-staged never operates on files that are excluded from version control. So it is not necessary to explicitly exclude stuff like node_modules/.

The formatter command may include a placeholder, {}, which will be replaced with the path of the file that is being formatted (with appropriate quoting). This is useful if your formatter needs to know the file extension to determine how to format or to lint each file. For example:

$ git-format-staged -f 'prettier --stdin-filepath {}' '*.js' '*.css'

Do not attempt to read or write to {} in your formatter command! The placeholder exists only for referencing the file name and path.

Check staged changes with a linter without formatting

Perhaps you do not want to reformat files automatically; but you do want to prevent files from being committed if they do not conform to style rules. You can use git-format-staged with the --no-write option, and supply a lint command instead of a format command. Here is an example using ESLint:

$ git-format-staged --no-write -f 'eslint --stdin --stdin-filename {} >&2' 'src/*.js'

If this command is run in a pre-commit hook, and the lint command fails the commit will be aborted and error messages will be displayed. The lint command must read file content via stdin. Anything that the lint command outputs to stdout will be ignored. In the example above eslint is given the --stdin option to tell it to read content from stdin instead of reading files from disk, and messages from eslint are redirected to stderr (using the >&2 notation) so that you can see them.

Set up a pre-commit hook

A git pre-commit hook runs automatically whenever you make a commit, before your editor opens to write a commit message. If formatting fails with a non-zero exit status it will cancel the commit, requiring you to fix the problem before trying again. (You can always skip a pre-commit hook by running git commit --no-verify.) But in most cases you will have correctly formatted files at all times, without having to think about it again after setup. Whenever a file is changed as a result of formatting on commit you will see a message in the output from git commit.

There are a number of options for setting up a git pre-commit hook depending on the software ecosystem you are working with.

Write a pre-commit hook manually

You can write a hook manually by creating the file .git/hooks/pre-commit, and making it executable. A hook set up this way will not automatically propagate to other clones, so every collaborator will have to do this themselves.

Nix devShell

If you use a Nix devShell you can use nix-git-hooks to help set up a pre-commit hook automatically. You can either automatically install hooks for everyone who uses the devShell, or provide a command that collaborators can run to easily opt in to hooks. Take a look at how this repo uses nix-git-hooks in flake.nix.

Npm, yarn, pnpm, or bun

Husky will automatically install git hooks for all project collaborators after running package manager commands.

Rust with Cargo

cargo-husky is like Husky, but for Rust projects.

and more!

See more hook management options in awesome-git and awesome-git-hooks.

Comparisons to similar utilities

There are other tools that will format or lint staged files. What distinguishes git-format-staged is that when a file has both staged and unstaged changes git-format-staged ignores the unstaged changes; and it leaves unstaged changes unstaged when applying formatting.

Some linters (such as precise-commits) have an option to restrict linting to certain lines or character ranges in files, which is one way to ignore unstaged changes while linting. The author is not aware of a utility other than git-format-staged that can apply any arbitrary linter so that it ignores unstaged changes.

Some other formatting utilities (such as pre-commit) use a different strategy to keep unstaged changes unstaged:

• stash unstaged changes
• apply the formatter to working tree files
• stage any resulting changes
• reapply stashed changes to the working tree.

The problem is that you may get a conflict where stashed changes cannot be automatically merged after formatting has been applied. In those cases the user has to do some manual fixing to retrieve unstaged changes. As far as the author is aware git-format-staged is the only utility that applies a formatter without touching working tree files, and then merges formatting changes to the working tree. The advantage of merging formatting changes into unstaged changes (as opposed to merging unstaged changes into formatting changes) is that git-format-staged is non-lossy: if there are conflicts between unstaged changes and formatting the unstaged changes win, and are kept in the working tree, while staged/committed files are formatted properly.

Another advantage of git-format-staged is that it has no dependencies beyond Python and git, and can be dropped into any programming language ecosystem.

Some more comparisons:

• lint-staged lints and formats staged files. At the time of this writing it does not have an official strategy for ignoring unstaged changes when linting, or for keeping unstaged changes unstaged when formatting. But lint-staged does provide powerful configuration options around which files should be linted or formatted, what should happen before and after linting, and so on.
• pretty-quick formats staged files with prettier. By default pretty-quick will abort the commit if files are partially staged to allow the user to decide how to re-stage changes from formatting. The result is more manual effort compared to git-format-staged.
• the one-liner git diff --diff-filter=d --cached | grep '^[+-]' | grep -Ev '^(--- a/|\+\+\+ b/)' | LINT_COMMAND (described here) extracts changed hunks and feeds them to a linter. But linting will fail if the linter requires the entire file for context. For example a linter might report errors if it cannot see import lines.