git-cli-agentic

# 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:** ```bash git status git log --oneline -5 git diff --stat ``` The `-C` flag is only needed when targeting a different repository from your current directory: ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # Unstaged changes git diff --numstat # Staged changes git diff --cached --numstat # Both (working tree vs HEAD) git diff HEAD --numstat ``` ### Specific Comparisons ```bash # Against specific commit git diff $COMMIT --numstat # Between branches git diff main..feature --numstat # Between commits git diff $COMMIT1..$COMMIT2 --name-status ``` ### Pathspecs: use `:(glob)` for `**` A plain git pathspec is not a gitignore-style glob. Without magic, `*` matches across `/` and `**` is just two of them, so a filter can silently miss files: | Pathspec | `src/proxy.ts` | `src/lib/a.ts` | |----------|:---:|:---:| | `'src/**/*.ts'` | no (needs a second `/`) | yes | | `':(glob)src/**/*.ts'` | yes | yes | | `'src/*.ts'` | yes | yes (`*` crosses `/`) | | `':(glob)src/*.ts'` | yes | no | ```bash git diff --name-only origin/main...HEAD -- ':(glob)src/**/*.ts' ``` The miss produces no error, only a shorter file list. A changed-files step that feeds CI checks then skips top-level files without anyone noticing. Test a new pathspec against a repo that has both top-level and nested matches. ## Log Operations ### Custom Format ```bash # 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 ```bash # 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 ```bash # 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 ```bash # Ahead/behind count git rev-list --left-right --count origin/main...HEAD # Output: <behind>\t<ahead> ``` ## Remote Operations ```bash # 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 ```bash # Stage specific files git add path/to/file # Stage several files: name each path you changed (bulk staging also # sweeps up another agent's uncommitted work in a shared checkout) git add src/a.ts src/b.ts tests/a.test.ts # Stage selected hunks of one file git add -p path/to/file # Unstage file git restore --staged path/to/file # Discard changes git restore path/to/file ``` ## Commit Operations ```bash # 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 ```bash # 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+): ```markdown - 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: ```bash # 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 1. **Use porcelain v2** for status when parsing programmatically 2. **Use --numstat** for diff when counting changes 3. **Use custom --format** for log when extracting specific fields 4. **Always add 2>/dev/null fallback** in context expressions 5. **Prefer git switch/restore** over checkout for clarity