Skip to content

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)**/*.md

The 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 ​

SignatureShortWhat 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 exist

Rarely 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:

PatternMatches
**/*.mdAll 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]*.logLog files starting with a digit
dir/**/*.test.tsAll 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=true

exclude — 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_OUTPUT

DevOps 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 ​

CommandPathspec behaviour
git addIndex update — pathspec filters staged content
git diffWorking tree vs index — pathspec filters comparison scope
git logCommit history — pathspec filters commits touching those paths
git grepFile content — pathspec limits search scope
git cleanUntracked files — pathspec controls what gets removed
git rmRemove from index + working tree — pathspec targets files
git ls-filesList tracked files — pathspec filters the list

Most commands accept multiple pathspecs. Use multiple to build complex inclusion/exclusion sets.

  • docs/recipes/pathspec-quick.md — one-page cheat sheet
  • docs/devops-workflows/git-attributes-filter-drivers.md — defining attributes that (attr:) depends on
  • docs/devops-workflows/git-diff-devops.md — diff-based CI gates that use pathspec scope narrowing

Git Master — Git Reference for Every Skill Level