Git Reference ยท Files and Formats
The filter attribute
Reference for the filter attribute in .gitattributes: clean and smudge commands, process filters, required, and how Git LFS uses them to swap content.
The filter attribute attaches a pair of commands to matching files. The clean command transforms the file as it goes into the repository (on git add), and the smudge command transforms it on the way back out (on checkout). Git LFS is the best-known user: clean replaces a big file with a small pointer, smudge fetches the real content again.
Like diff and merge drivers, the attribute only names the filter. The commands live in configuration as filter.<name>.clean, filter.<name>.smudge, and optionally filter.<name>.process and filter.<name>.required.
*.psd filter=lfs diff=lfs merge=lfs -text
secrets.env filter=redact
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
<pattern> filter=<name> git config filter.<name>.clean "<command>" git config filter.<name>.smudge "<command>" git config filter.<name>.process "<long-running command>" git config filter.<name>.required true
| Name | Description |
|---|---|
filter.<name>.clean |
Reads the working-tree file on standard input, writes the repository form to standard output. %f expands to the file name. |
filter.<name>.smudge |
Reads the repository form on standard input, writes the working-tree form to standard output. %f is available here too. |
filter.<name>.process |
A single long-running helper that handles many files over a pkt-line protocol. Much faster than starting one process per file; used by Git LFS. |
filter.<name>.required |
If true, a failing or missing filter aborts the operation instead of being skipped. |
Edge cases: if a filter command is missing and required is not set, Git just stores the file unchanged. Filters run before line-ending conversion on the way in and after it on the way out.
Usage notes
- Make the pair round-trip.
clean(smudge(x))should equalx. Otherwisegit statusshows modified files forever. - Filters run often. Every
git add,git diffandgit statusthat must look at the file may runclean. Keep commands fast, or useprocess. - Never use filters for secrets you want to keep out of history by security. The working-tree copy is unchanged, and teammates who lack the smudge command see the redacted form. Use a secret manager.
- Mark
requiredfor tools like LFS. Without it, a machine missing the tool silently commits full-size files or checks out pointer text. - Config is per clone. Anyone cloning needs the filter definitions;
git lfs installsets them for you. - Filters and archives.
git archiveruns smudge for files with a filter attribute. - Debugging. Run the clean command by hand on a sample file and compare with
git cat-file -p. - Not for formatting code. Reformatting on add produces surprising diffs; use a pre-commit hook or a formatter in CI.