Git Cli Agentic

---
name: git-cli-agentic
description: Git commands with porcelain and machine-readable output for agent workflows. Use when scripting status/diff/log, porcelain=v2, --numstat counts, custom --format placeholders, or branch tracking info.
user-invocable: false
allowed-tools: Bash(git status *), Bash(git diff *), Bash(git log *), Bash(git branch *), Bash(git remote *), Bash(git add *), Bash(git commit *), Bash(git push *), Bash(git restore *), Read
created: 2025-01-16
modified: 2026-09-24
reviewed: 2026-04-25
---

# 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 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

```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