Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Revisions and Pathspecs

Pathspec magic: :(glob), :(exclude) and more

Reference for Git pathspec magic signatures: top, literal, icase, glob, attr, exclude, the short forms :/ and :!, and how to combine them safely.

Pathspec magic changes how a single pathspec is interpreted. It is written as a prefix: either the long form :(keyword,keyword)pattern or a short form made of a colon and one or more punctuation characters, such as :/ or :!. The prefix applies only to the pattern that follows it, so one command line can mix plain paths and magic ones.

The most useful pieces are exclude (leave files out), top (anchor at the repository root), glob (shell-style matching where * stops at slashes and ** crosses them), icase (ignore case) and attr (match files by their gitattributes). A command line with only excludes starts from "everything", so git diff -- ':!vendor' means "all changes except under vendor/".

Terminal
git log -- ':(exclude)*.lock'
git add ':(glob)src/**/*.js'
git grep TODO -- ':(top)docs'

Try it

Bash exclude, top and glob

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 icase, literal and attr

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
:(<magic>[,<magic>...])<pattern>
:<short-signature><pattern>
:                       # lone colon plus pattern: no magic, handy to escape
Long keyword Short Effect
top / Match from the repository root instead of the current directory.
literal Treat *, ?, [ and \ as ordinary characters.
icase Case-insensitive matching.
glob Shell-style: * and ? do not match /; **/ and /** cross directories.
attr:<spec> Match files whose attributes fit: name (set), -name (explicitly unset), !name (unspecified), name=value. Several, separated by spaces.
exclude ! or ^ Remove matching paths from the selected set.

Short signatures can be stacked (:/!docs), and a lone : before a pattern that starts with a magic character, such as ::!weird, switches magic off. Long keywords are separated by commas, as in :(top,icase)Readme.md.

Errors and edge cases: a command that does not support a keyword stops with an error such as fatal: ... pathspec magic not supported by this command. Unknown keywords fail with Invalid pathspec magic. :(glob) cannot be combined with :(literal), and an exclude pathspec needs the command to support it (a few plumbing commands do not).

Usage notes

  • Order does not matter for excludes: Git first collects everything matched by the positive pathspecs, then removes what the excludes match. A command with only excludes uses . as the positive set.
  • :/ is not :/text. A colon and slash before a path means the repository root (the same as top); a colon and slash used as a revision searches commit messages. See :/text and ^{/text}.
  • Quote everything. ! triggers history expansion in interactive bash, and *, ( and ) mean things to every shell: ':(exclude)*.log' or ':!*.log'.
  • Default matching is not glob. In plain pathspecs * matches across slashes, so *.js finds nested files. With glob, *.js matches only the top level, and you need **/*.js to go deeper.
  • Environment switches: GIT_GLOB_PATHSPECS=1 makes every pathspec glob, GIT_NOGLOB_PATHSPECS=1 makes them literal, GIT_ICASE_PATHSPECS=1 makes them case-insensitive, and GIT_LITERAL_PATHSPECS=1 turns all magic off.
  • Support differs by command. Excludes work in add, log, diff, grep, ls-files, status, checkout, restore and commit; check the command if you see "unsupported magic".
  • attr reads the working tree attributes of each file, so :(attr:!filter) can select files that do not use a filter. Combine with other keywords as in :(top,attr:generated,exclude).
  • Common pattern: keep generated files out of diffs and logs with a generated attribute plus ':(exclude,attr:generated)'; for hand-written noise, ':!*.lock' is enough.