Appearance
Git Pathspec Magic — Precision Path Filtering for CI/CD
Pathspecs are how you tell Git which files to operate on. Most engineers know the basics — a filename, a directory, a glob — but Git supports magic signatures that change how pathspecs are interpreted. These signatures let you write precise CI scripts that would otherwise require grep pipelines or multiple commands.
This guide covers the 7 magic signatures, how to combine them, and the DevOps patterns where each one earns its keep.
What is a pathspec magic signature?
A pathspec is the path argument you pass to git add, git log, git diff, git grep, git clean, git rm, and many others. A magic signature is a prefix that changes how that path is matched.
Short form: :(signature)path Long form: :(signature1,signature2)path
bash
# No magic — relative path, literal matching
git log -- README.md
# Magic: treat path as case-insensitive
git log -- :(icase)readme.md
# Magic: treat path as glob, root-relative
git log -- :(top,glob)**/*.mdThe short single-letter forms also exist: :/ for top, :! for exclude, :\ for literal. The long forms are easier to read in scripts.
The 7 magic signatures
| Signature | Short | What it does |
|---|---|---|
top | / | Force matching from repo root, not cwd |
literal | \ | Disable glob/wildcard interpretation |
icase | — | Case-insensitive matching |
glob | — | Enable full glob patterns (**, [a-z], {a,b}) |
attr | — | Match files by .gitattributes attribute |
exclude | ! | Invert match — exclude matching paths |
(recursive) | — | Match paths recursively (default for directories) |
top — root-relative paths from any subdirectory
Without top, pathspecs are relative to the current working directory. With top, the match is against the repo root regardless of where the command runs.
bash
# From docs/ subdirectory:
git log -- :(top)README.md # Works — pathspec is root-relative
git log -- README.md # Empty — Git looks for docs/README.md
# CI use case: consistent file-watch regardless of runner working dir
git diff --name-only HEAD~1..HEAD -- :(top)config/This is the safest choice in CI scripts. The runner's working-directory setting should never matter.
literal — disable glob interpretation
When a path contains *, ?, or [, Git normally interprets them as wildcards. literal turns that off.
bash
# Without literal: matches any file ending in .config.js
git add -- :(glob)*.config.js
# With literal: matches only the literal file named exactly that
git show HEAD:path/to/*.config.js # May match multiple
git show HEAD:path/to/:(literal)*.config.js # Fails — file doesn't existRarely needed in scripts, but critical when a file path genuinely contains glob characters — or when reading a path from user input that shouldn't be interpreted.
icase — case-insensitive matching
bash
# Find all Readme variants
git log --all -- :(icase)**/readme*
# Works on any filesystem, not just case-insensitive ones
# Same result on Linux (ext4, case-sensitive) and macOS (APFS, case-insensitive)Useful for portability: CI runners on Linux vs macOS may have different case conventions in cloned repos. icase normalises the difference.
glob — full glob patterns
Without glob or literal, Git pathspecs use a limited glob: * matches anything except /, and ? matches one character except /. With glob, you get the full set:
| Pattern | Matches |
|---|---|
**/*.md | All markdown files in any directory |
**/config/** | Any file nested under any config/ directory |
**/{dev,prod}/** | Files under dev/ or prod/ at any depth |
**/[0-9]*.log | Log files starting with a digit |
dir/**/*.test.ts | All test files under dir/ and all subdirs |
bash
# CI: find all config files at any depth
git diff --name-only HEAD~1..HEAD -- :(glob)**/config.{json,yaml,toml}
# CI: find everything changed except test files, at any depth
git diff --name-only HEAD~1..HEAD -- :(exclude,glob)**/*.test.*Mnemonic: glob behaves like ** in .gitignore. It's the most useful single signature for monorepo CI.
attr — match files by .gitattributes attribute
This is the most powerful signature for infrastructure pipelines. It uses the .gitattributes attributes you already define.
bash
# Attributes in .gitattributes:
# *.tf linguist-language=Terraform diff=terraform
# *.yaml merge=union
# CI: only Terraform files
git log --all -- :(attr:linguist-language=Terraform)
# CI: only files with a custom merge driver
git diff --name-only HEAD~1..HEAD -- :(attr:merge=union)Practical CI patterns with attr:
bash
# Deploy gate: did any infrastructure file change?
git diff --exit-code HEAD~1..HEAD -- :(attr:infrastructure=true)
# Build gate: did any source file change?
git diff --exit-code HEAD~1..HEAD -- :(attr:source=true)
# Review scope: show only config files for audit
git diff HEAD~1..HEAD -- :(attr:config=true)Define attributes in .gitattributes:
# .gitattributes
*.tf infrastructure=true diff=terraform
*.yaml infrastructure=true
Dockerfile source=true infrastructure=true
src/** source=true
test/** test=true
*.spec.ts test=trueexclude — exclude matching paths
bash
# Everything except generated files
git diff --name-only HEAD~1..HEAD -- . :(exclude,glob)**/generated/**
git diff --name-only HEAD~1..HEAD -- . :(exclude,glob)**/*.pb.go
# Everything except tests (combined with glob)
git diff --name-only HEAD~1..HEAD -- . :(exclude,glob)**/*.test.*
# Everything except lockfiles (dependency audit without noise)
git log --oneline -- . ':(exclude)package-lock.json' ':(exclude)yarn.lock'The short form :!path is common in CI scripts:
bash
git diff --name-only HEAD~1 -- . ':!package-lock.json' ':!*.snap'Order matters. Git evaluates pathspecs left to right. Exclude after include:
bash
# Right: include everything, then exclude
git diff --name-only HEAD~1 -- . ':(exclude,glob)**/test/**'
# Wrong: exclude first has nothing to exclude yet
git diff --name-only HEAD~1 -- ':(exclude,glob)**/test/**' .A pathspec with only exclusions matches nothing — you must include something first (. covers the whole tree).
Combining signatures
Multiple signatures go in parentheses, comma-separated:
bash
### root-relative glob with exclusion
git log -- :(top,glob,exclude)**/test/**Order inside the parens doesn't matter. All are applied to the same path.
DevOps scenario: monorepo CI scope detection
Here's a complete monorepo CI job that determines what changed and routes to the right pipeline:
bash
#!/bin/bash
# ci-scope.sh - detect change scope for targeted CI
set -euo pipefail
CHANGED=$(git diff --name-only HEAD~1..HEAD)
# Check each scope independently
if echo "$CHANGED" | grep -q "$(git ls-files ':(attr:infrastructure=true)')"; then
echo "scope=infrastructure" >> $GITHUB_OUTPUT
fi
if echo "$CHANGED" | git diff --exit-code HEAD~1..HEAD -- ':(exclude,glob)**/*.md' >/dev/null; then
echo "docs-only=true" >> $GITHUB_OUTPUT
fi
# Or use pathspec directly in a diff to check scope
git diff --exit-code HEAD~1..HEAD -- :(attr:source=true) || echo "scope=app" >> $GITHUB_OUTPUTDevOps scenario: git grep across scoped paths
Pathspecs work with git grep too. Search only infrastructure files:
bash
git grep --cached -l 'REGION=' -- :(attr:infrastructure=true) :(exclude,glob)**/generated/**Or find every reference to a deprecated API, excluding lockfiles:
bash
git log --all -S 'deprecated_func' -- ':(exclude)*.lock'Pitfalls
Pathspec order matters. Exclusions need a preceding inclusive pathspec. An array of pathspecs like . :(exclude)foo works; :(exclude)foo alone matches nothing.
Shell quoting. The colon and parentheses are shell metacharacters. Always quote:
bash
# Wrong: shell eats the parens
git diff HEAD~1 -- :(exclude)*.lock
# Right
git diff HEAD~1 -- ':(exclude)*.lock'attr requires the attribute to exist. If .gitattributes has infrastructure=true but only on half the files, :(attr:infrastructure=true) matches only those half. Files with no attribute setting are not matched. Use :(attr:-infrastructure) (hyphen prefix) to match files that do not have the attribute.
glob is not fnmatch. * still does not match / — you need **/ to cross directory boundaries, just like .gitignore.
top vs commit paths. top works on the working tree. When you pass a tree-ish like HEAD:path, the pathspec uses the tree structure, not the working tree. The two can differ if the index is dirty.
Command reference
| Command | Pathspec behaviour |
|---|---|
git add | Index update — pathspec filters staged content |
git diff | Working tree vs index — pathspec filters comparison scope |
git log | Commit history — pathspec filters commits touching those paths |
git grep | File content — pathspec limits search scope |
git clean | Untracked files — pathspec controls what gets removed |
git rm | Remove from index + working tree — pathspec targets files |
git ls-files | List tracked files — pathspec filters the list |
Most commands accept multiple pathspecs. Use multiple to build complex inclusion/exclusion sets.
Related
docs/recipes/pathspec-quick.md— one-page cheat sheetdocs/devops-workflows/git-attributes-filter-drivers.md— defining attributes that(attr:)depends ondocs/devops-workflows/git-diff-devops.md— diff-based CI gates that use pathspec scope narrowing