Git Reference ยท Revisions and Pathspecs
Pathspec: selecting files
Reference for Git pathspecs: how patterns select files in add, log, diff and checkout, how globs and directories match, and when to use the -- separator.
A pathspec is the part of a Git command line that says which files you mean. It appears after the revision arguments in commands such as git add, git log, git diff, git restore, git grep, git ls-files and git commit. Without a pathspec most commands act on the whole tree; with one, they act only on matching paths.
A plain pathspec is a path relative to the current directory. Naming a directory selects everything under it. Wildcards (*, ?, [...]) are expanded by Git itself, using shell-like matching where, by default, * also crosses slashes. Special prefixes, called pathspec magic, change the rules; see Pathspec magic.
git log -- src/ docs/readme.md git add '*.js' git diff HEAD -- . ':!vendor'
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
git <command> [<options>] [<revisions>] [--] [<pathspec>...]
| Piece | Meaning |
|---|---|
path/to/file |
Exactly that file. |
dir or dir/ |
Everything inside the directory, recursively. |
*, ?, [a-c] |
Wildcards. By default * and ? match any character, including /. |
. |
The current directory and everything below it. |
-- |
Ends options and revisions; everything after it is a pathspec. |
:(magic)pattern, :!pattern |
Pathspec magic; see the next page. |
Errors and edge cases: fatal: pathspec 'x' did not match any files comes from commands that require a match (add, rm, checkout). Read-only commands like log and diff just return nothing. fatal: ambiguous argument 'x': both revision and filename means you left out --. git add also refuses ignored paths unless you pass -f.
Usage notes
- Quote wildcards. If the shell expands
*.jsfirst it only sees files in the current directory. Quoting ('*.js') hands the pattern to Git, which also matches files in subdirectories and files that are no longer on disk. --is cheap insurance. Without it Git guesses whether a word is a revision or a path and refuses when it could be both. Scripts should always write-- <path>.- Paths are relative to the current directory, except in the
:/top-of-tree form. Run from a subdirectory,git add .adds only that subtree, whilegit add -A(since Git 2.0) covers the whole tree. - A pathspec filters history too.
git log -- fileshows only commits that touchedfileand, by default, simplifies the history; add--followfor a single file across renames, or--full-historyfor every side branch. - Removed files still match in
log,diffandrestore --source=<rev>, because the pathspec is matched against tree contents in the commits you name, not against your disk. - Pathspec is not
.gitignoresyntax. In a pathspec*crosses directories by default and there is no anchoring or negation with!(the:!prefix is magic, not a pattern);.gitignorerules are described in Gitignore-style patterns. - Empty pathspec means "everything" for most commands, but
git addwithout arguments does nothing andgit rmrequires paths. - Literal characters: if a file name really contains
*or?, write:(literal)name, or setGIT_LITERAL_PATHSPECS=1for the command. - Reading paths from a file is possible with
--pathspec-from-file=<file>(and--pathspec-file-nul) inadd,commit,reset,restoreandrm.