laurigates Git CLI Agentic Patterns
When to Use This Skill
| Use this skill when... | Use the alternative when... |
|---|---|
Writing scriptable git status/diff/log calls in porcelain or --format mode |
Use gh-cli-agentic for gh JSON queries against the GitHub API |
Needing --porcelain=v2 status, --numstat diff counts, or custom --format log placeholders |
Use git-commit-workflow for staging conventions and commit message structure |
| Reading branch tracking info or main-branch-development push patterns | Use git-branch-pr-workflow for the broader branch + PR design choices |
| Producing deterministic output for parsers and downstream tooling | Use git-derive-docs to mine commit history for rules/PRDs/ADRs/PRPs |
Optimized git commands for AI agent consumption using porcelain output and stable formats.
Core Principle
Use --porcelain for machine-readable output that remains stable across Git versions and user configurations.
Working Directory
Run git commands directly — your working directory is the repo:
git status
git log --oneline -5
git diff --stat
The -C flag is only needed when targeting a different repository from your current directory:
# Submodule: run command against parent repo
git -C "$(git rev-parse --show-toplevel)" remote get-url origin
# Script: iterate over multiple repos
for repo in repos/*; do
git -C "$repo" status --porcelain
done
Status Operations
Porcelain Status
# Version 2 porcelain with branch info (recommended)
git status --porcelain=v2 --branch
# Version 1 porcelain (simpler)
git status --porcelain
# Short format (human-readable but stable)
git status --short --branch
Porcelain v2 Format:
# branch.oid <commit>
# branch.head <branch>
# branch.upstream <upstream>
# branch.ab +<ahead> -<behind>
1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><tab><origPath>
? <path>
! <path>
Status Codes:
| Code | Meaning |
|---|---|
| M | Modified |
| A | Added |
| D | Deleted |
| R | Renamed |
| C | Copied |
| ? | Untracked |
| ! | Ignored |
Quick Checks
# Check if clean (empty output = clean)
git status --porcelain
# Count changed files
git status --porcelain | wc -l
# Check for uncommitted changes
git diff --quiet || echo "has changes"
Diff Operations
Stat Output
# File change summary
git diff --stat
# Numeric stats (machine-readable)
git diff --numstat
# Name and status only
git diff --name-status
# Names only
git diff --name-only
Numstat Format: <added>\t<deleted>\t<filename>
Staged vs Unstaged
# Unstaged changes
git diff --numstat
# Staged changes
git diff --cached --numstat
# Both (working tree vs HEAD)
git diff HEAD --numstat
Specific Comparisons
# Against specific commit
git diff $COMMIT --numstat
# Between branches
git diff main..feature --numstat
# Between commits
git diff $COMMIT1..$COMMIT2 --name-status
Log Operations
Custom Format
# Hash and subject only
git log --format='%H %s' -n 10
# Oneline (built-in)
git log --oneline -n 10
# With stats
git log --oneline --stat -n 5
# Machine-parseable with multiple fields
git log --format='%H|%an|%ae|%s' -n 10
Format Placeholders:
| Placeholder | Meaning |
|---|---|
%H |
Full commit hash |
%h |
Short hash |
%s |
Subject |
%b |
Body |
%an |
Author name |
%ae |
Author email |
%ad |
Author date |
%cn |
Committer name |
Filtering
# By author
git log --author="name" --oneline -n 10
# By date range
git log --since="2025-01-01" --oneline
# By path
git log --oneline -n 10 -- path/to/file
# Merge commits only
git log --merges --oneline -n 5
Branch Operations
Branch Info
# List with tracking info
git branch -vv
# Formatted output
git branch --format='%(refname:short) %(upstream:short) %(upstream:track)'
# Current branch only
git branch --show-current
# Remote branches
git branch -r --format='%(refname:short)'
Tracking Status
# Ahead/behind count
git rev-list --left-right --count origin/main...HEAD
# Output: <behind>\t<ahead>
Remote Operations
# List remotes with URLs
git remote -v
# Get specific remote URL
git remote get-url origin
# Show remote details
git remote show origin
Staging Operations
# Stage specific files
git add path/to/file
# Stage all modified tracked files
git add -u
# Stage everything
git add -A
# Unstage file
git restore --staged path/to/file
# Discard changes
git restore path/to/file
Commit Operations
# Simple commit
git commit -m "message"
# With body (heredoc)
# Inside <<'EOF' (quoted delimiter), backticks, $, and \ are already
# literal — never backslash-escape them, or the backslash survives into
# the commit message.
git commit -m "$(cat <<'EOF'
Subject line
Body paragraph with `code` and $vars written verbatim.
Co-Authored-By: Name <email>
EOF
)"
# Amend last commit (use carefully)
git commit --amend -m "new message"
Push Operations
# Push current branch
git push origin HEAD
# Push to different remote branch (main-branch development)
git push origin main:feature-branch
# Push commit range
git push origin start^..end:feature-branch
# Set upstream
git push -u origin HEAD
Agentic Optimizations
| Context | Command |
|---|---|
| Quick status | git status --porcelain=v2 --branch |
| Changed files | git diff --name-status |
| Staged changes | git diff --cached --numstat |
| Recent commits | git log --format='%h %s' -n 5 |
| Branch tracking | git branch -vv --format='%(refname:short) %(upstream:track)' |
| Current branch | git branch --show-current |
Error Handling in Context
Use 2>/dev/null to suppress errors in context expressions (do NOT use || fallbacks - blocked by Claude Code 2.1.7+):
- Git status: !`git status --porcelain=v2 --branch`
- Current branch: !`git branch --show-current`
- Remote URL: !`git remote -v`
Combining with GH CLI
For GitHub-specific operations, combine with gh commands:
# Get repo owner/name
gh repo view --json nameWithOwner --jq '.nameWithOwner'
# Then use in git operations
git push origin main:$(gh pr view --json headRefName --jq '.headRefName')
Best Practices
- Use porcelain v2 for status when parsing programmatically
- Use --numstat for diff when counting changes
- Use custom --format for log when extracting specific fields
- Always add 2>/dev/null fallback in context expressions
- Prefer git switch/restore over checkout for clarity