Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
git log -- src/ docs/readme.md
git add '*.js'
git diff HEAD -- . ':!vendor'

Try it

Bash Directories, wildcards and the dot

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 Why the double dash exists

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
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 *.js first 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, while git add -A (since Git 2.0) covers the whole tree.
  • A pathspec filters history too. git log -- file shows only commits that touched file and, by default, simplifies the history; add --follow for a single file across renames, or --full-history for every side branch.
  • Removed files still match in log, diff and restore --source=<rev>, because the pathspec is matched against tree contents in the commits you name, not against your disk.
  • Pathspec is not .gitignore syntax. In a pathspec * crosses directories by default and there is no anchoring or negation with ! (the :! prefix is magic, not a pattern); .gitignore rules are described in Gitignore-style patterns.
  • Empty pathspec means "everything" for most commands, but git add without arguments does nothing and git rm requires paths.
  • Literal characters: if a file name really contains * or ?, write :(literal)name, or set GIT_LITERAL_PATHSPECS=1 for the command.
  • Reading paths from a file is possible with --pathspec-from-file=<file> (and --pathspec-file-nul) in add, commit, reset, restore and rm.