git-format-staged
Consider a project where you want all code formatted consistently. So you use
a formatting command. (For example I use prettier-standard in my
Javascript 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
Requires Python version 3 or 2.7.
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
If you do not use npm 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' '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 both the formatter command and the file pattern
are quoted. If you prefer you may let your shell expand a file glob for you.
This command is equivalent if your shell supports globstar notation:
$ git-format-staged --formatter 'prettier --stdin' src/**/*.js
Zsh supports globstar by default. Bash only supports globstar if a certain
shell option is set. Do not rely on globstar in npm scripts!
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 >&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 with Husky
Follow these steps to automatically format all Javascript files on commit in
a project that uses npm.
Install git-format-staged, husky, and a formatter (I use prettier-standard):
$ npm install --save-dev git-format-staged husky prettier-standard
Add a "precommit"
script in package.json
:
"scripts": {
"precommit": "git-format-staged -f prettier-standard '*.js'"
}
Once again note that the '*.js'
pattern is quoted! If the formatter command
included arguments it would also need to be quoted.
That's it! Whenever a file is changed as a result of formatting on commit you
will see a message in the output from git commit
.