Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
*.psd filter=lfs diff=lfs merge=lfs -text
secrets.env filter=redact

Try it

Bash A clean filter that strips a value

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.

Bash Smudge on checkout and the required flag

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

Terminal
<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 equal x. Otherwise git status shows modified files forever.
  • Filters run often. Every git add, git diff and git status that must look at the file may run clean. Keep commands fast, or use process.
  • 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 required for 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 install sets them for you.
  • Filters and archives. git archive runs 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.