CLI Reference

When you invoke the Git AI binary as git it will proxy the arguments to git and pipe the output and exist code back to you.

To run Git AI specific commands you invoke the same binary as git-ai. The symlinks and $PATH export the install scripts setup sets all this up on your machine.

git-ai <command> [options]

User Commands

blame

Enhanced version of git blame that shows AI authorship attribution alongside traditional git blame.

git-ai blame <file>

Arguments:

• <file> - Path to the file to blame (required)

Options: Mostly API Compatible, supports same options as git blame.

diff

Show a git-style unified diff with AI authorship annotations for each changed line. Similar to git diff, but annotates additions and deletions with AI or human attribution.

# Show diff for a single commit (from parent to commit)
git-ai diff <commit>

# Show diff between two commits
git-ai diff <commit1>..<commit2>

# Examples
git-ai diff HEAD                  # Diff of most recent commit
git-ai diff abc123                # Diff of specific commit
git-ai diff main..feature-branch  # Diff between branches
git-ai diff abc123..def456        # Diff between specific commits

Arguments:

• <commit> - Show diff from this commit's parent to the commit
• <commit1>..<commit2> - Show diff between two commits (standard git range syntax)

Output Format:

Each changed line (additions + and deletions -) is annotated with authorship information:

• 🤖toolname - Line was authored by an AI tool (e.g., 🤖cursor, 🤖claude)
• 👤username - Line was authored by a human (shows git username)
• [no-data] - No AI authorship data available for this line

The annotations appear at the end of each changed line. Context lines (unchanged) are not annotated.

Example Output:

diff --git a/src/main.rs b/src/main.rs
index 5716ca5..8f94139 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -10,3 +10,5 @@ fn main() {
     println!("Hello");
-    let x = 1;        👤alice
+    let x = 2;        🤖cursor
+    let y = 3;        🤖cursor
     println!("World");

Notes:

• Output is colored when displayed in a terminal (red for deletions, green for additions)
• For deletions, attribution shows who originally authored that line in the old commit
• For additions, attribution shows who authored that line in the new commit
• Works with commit ranges to see all changes between any two commits

stats

Show AI authorship statistics for a commit. Displays how much code was written by humans vs AI.

# Show stats for current HEAD
git-ai stats

# Show stats for specific commit
git-ai stats <commit-sha>

# Show stats for a range of commits (same semantics as `git log <start>..<end>`)
git-ai stats <start>..<end>

# Show stats for the entire history (from Git's empty tree to HEAD)
git-ai stats 4b825dc642cb6eb9a060e54bf8d69288fbee4904..HEAD

# Output in JSON format
git-ai stats --json
git-ai stats <commit-sha> --json
git-ai stats <start>..<end> --json

# Ignore specific files from stats (e.g., lockfiles, generated files)
# Exact filename matching
git-ai stats --ignore Cargo.lock
git-ai stats --ignore Cargo.lock package-lock.json yarn.lock  # Multiple patterns

# Glob pattern matching (use quotes to prevent shell expansion)
git-ai stats --ignore "*.lock"                    # All files ending in .lock
git-ai stats --ignore "*.generated.*"             # All generated files
git-ai stats --ignore "*.lock" "**/dist/**"       # Multiple patterns

# Shell glob expansion (no quotes needed if files exist in current directory)
git-ai stats --ignore *.lock                      # Shell expands to matching files
git-ai stats <start>..<end> --ignore *.lock *.json

# Combine exact and glob patterns
git-ai stats --ignore Cargo.lock "*.generated.js" package.lock

Options:

• <commit-sha> - Optional commit SHA (defaults to HEAD)
• <start>..<end> - Optional commit range; when provided, stats are computed over the entire range rather than a single commit
• --json - Output statistics in JSON format
• --ignore <pattern...> - Exclude files matching the pattern(s) from statistics. Supports:
  • Exact matches: Cargo.lock, package-lock.json
  • Glob patterns: *.lock, *.generated.*, **/target/**, node_modules/**
  • Multiple patterns: Space-separated patterns after a single --ignore flag
  • Shell expansion: Unquoted globs are expanded by the shell (e.g., *.lock → Cargo.lock yarn.lock)
  • Pattern is matched against both the full file path and just the filename
  • Quote patterns to prevent shell expansion and use glob matching instead

Output

When using --json, the command returns a JSON object with the following fields:

• human_additions: Number of lines in the commit attributed to humans (full or mixed). Calculated from final commit diff lines whose authorship attribution is human, including lines that originated from AI but were edited by a human before commit.
• mixed_additions: Number of AI-generated lines that were edited by humans before being committed. Calculated by intersecting AI-originated lines with human-edited changes prior to commit.
• ai_additions: Number of lines in the commit attributed to AI (full or mixed). Calculated from final commit diff lines with AI attribution, including lines later edited by humans.
• ai_accepted: Number of AI-generated lines committed without any human edits. Calculated as AI-originated lines that landed in the commit unchanged by humans.
• total_ai_additions: Total lines generated by AI while working toward this commit, whether or not they appear in the final diff. Includes accepted, mixed, and AI lines later removed during the session.
• total_ai_deletions: Total lines deleted by AI while working toward this commit, whether or not those deletions remain in the final diff.
• time_waiting_for_ai: Total wall-clock seconds spent waiting for AI responses during the commit’s working session(s).
• git_diff_added_lines: Raw number of added lines reported by the git diff for this commit.
• git_diff_deleted_lines: Raw number of deleted lines reported by the git diff for this commit.
• tool_model_breakdown: Object keyed by <tool>:<model> with per-tool metrics:
  • ai_additions, mixed_additions, ai_accepted, total_ai_additions, total_ai_deletions, time_waiting_for_ai (same definitions as above, scoped to that tool/model). For example, cursor/gpt-5

Notes:

• These categories are not mutually exclusive: for example, mixed_additions are counted in both human_additions and ai_additions, so human_additions + ai_additions can exceed git_diff_added_lines.
• Authorship is computed from tracked AI/human checkpoints and attribution over the final diff. “Mixed” means an AI-generated line was subsequently modified by a human before commit; “AI accepted” means an AI-generated line was committed without human edits.
• Empty lines are included in all statistics, for both humans and AI

show

Display the stored AI authorship log for a commit or list the logs for every commit in a range.

# Show log for a specific commit
git-ai show <commit>

# Show logs for every commit in a range
git-ai show <start>..<end>

Arguments:

• <commit> - Commit to inspect
• <start>..<end> - Inclusive commit range; all commits reachable from <end> but not <start> are shown, with each log preceded by its SHA

Output

• Prints the serialized authorship log for each matching commit, or No authorship data found for this revision when a commit has no stored log

show-prompt

Display a prompt record by its ID from authorship notes. Returns the prompt object from the most recent commit's authorship note where the prompt with the given ID is located, or from a specific commit if requested.

# Get the most recent occurrence of a prompt
git-ai show-prompt <prompt_id>

# Get prompt from a specific commit
git-ai show-prompt <prompt_id> --commit <rev>

# Get the Nth occurrence (0 = most recent, 1 = second most recent, etc.)
git-ai show-prompt <prompt_id> --offset <n>

Arguments:

• <prompt_id> - The prompt ID to look up (required)

Options:

• --commit <rev> - Look in a specific commit only (can be a commit SHA, HEAD, branch name, etc.). Mutually exclusive with --offset
• --offset <n> - Skip n occurrences before returning (0 = most recent, 1 = second most recent, etc.). Mutually exclusive with --commit

Output

Returns a JSON object with the following structure:

{
  "commit": "<commit_sha>",
  "prompt_id": "<prompt_id>",
  "prompt": {
    "agent_id": {
      "tool": "<tool_name>",
      "id": "<agent_id>",
      "model": "<model_name>"
    },
    "human_author": "<author_name>",
    "messages": [...],
    "total_additions": <number>,
    "total_deletions": <number>,
    "accepted_lines": <number>,
    "overriden_lines": <number>
  }
}

Notes:

• If --commit is specified, the command only searches in that specific commit's authorship note
• If --offset is specified (and --commit is not), the command searches through all commits containing the prompt ID, ordered from most recent to least recent, and returns the (N+1)th occurrence where N is the offset
• The --commit and --offset flags are mutually exclusive
• If the prompt is not found, the command exits with an error

install-hooks

Automatically configure Claude Code, Cursor and GitHub Copilot to send authorship information to the git-ai binary

git-ai install-hooks

Plumbing Commands (for AI Agents)

These commands are primarily used by AI agents (Claude Code, Cursor, GitHub Copilot) for authorship tracking. End users typically don't need to use these directly.

checkpoint

Checkpoint working changes and attribute them to an AI agent or human author.

# Basic checkpoint with preset
git-ai checkpoint <preset>

# Show the current working log
git-ai checkpoint --show-working-log

# Reset the working log
git-ai checkpoint --reset

Presets:

• claude - Claude AI integration
• cursor - Cursor editor integration
• github-copilot - GitHub Copilot integration
• mock_ai - Mock AI for testing

Options:

• --show-working-log - Display current working log without making changes
• --reset - Clear the working log

squash-authorship

Generate authorship information from squashed commits. Used when commits are squashed to reconstruct authorship metadata.

git-ai squash-authorship <branch> <new-sha> <old-sha>
git-ai squash-authorship <branch> <new-sha> <old-sha> --dry-run

Arguments:

• <branch> - Branch name (required)
• <new-sha> - New commit SHA after squash (required)
• <old-sha> - Old commit SHA before squash (required)

Options:

• --dry-run - Show what would be done without making changes

git-path

Print the path to the underlying git executable. Used by integrations to locate the git binary.

git-ai git-path

Version

Show the version of git-ai:

git-ai version
git-ai --version
git-ai -v