Git Plugin

version
0.0.7
GitHub stars
123

Install

/plugin install git@ai-helpers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.

Contents

Discovered from source

Skills 2

Name

openshift-developer:git-commit-format

Synopsis

/openshift-developer:git-commit-format

Description

Applies conventional commit formatting rules when generating commit messages. This skill is loaded as context for other skills and workflows — it defines the commit message format, required footers, and validation rules.

Implementation

Commit Message Format

<type>(<scope>): <description>

[optional body]

[footers]

Commit Types

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring (no functional changes)
  • test: Adding/updating tests
  • chore: Maintenance tasks
  • build: Build system or dependency changes
  • ci: CI/CD changes
  • perf: Performance improvements
  • revert: Revert previous commit

Breaking Changes

With ! to draw attention:

feat!: send email when product shipped

With BREAKING CHANGE footer:

feat: allow config to extend other configs

BREAKING CHANGE: `extends` key now used for extending config files

Required Footers

Signed-off-by

ALWAYS include Signed-off-by footer with name and email.

Get credentials in this priority order:

  1. Environment variables: $GIT_AUTHOR_NAME and $GIT_AUTHOR_EMAIL
  2. Git config: git config user.name and git config user.email
  3. If neither configured, ask user to provide details
Commit-Message-Assisted-by

ALWAYS include when Claude assists with creating or generating the commit message:

Commit-Message-Assisted-by: Claude (via Claude Code)

Gitlint Validation Rules

  • Run make run-gitlint to validate commit messages (if the repo has a gitlint target)
  • Title line: 120 characters maximum
  • Body line: 140 characters maximum per line
  • Use conventional commit format
  • Include required footers (Signed-off-by)
  • No trailing whitespace

Return Value

  • Commit message: A conventional commit message with type, scope, description, body, and all required footers

Examples

  1. Simple commit:

    docs: correct spelling of CHANGELOG
    
    Signed-off-by: Jane Doe <jdoe@example.com>
    Commit-Message-Assisted-by: Claude (via Claude Code)
    
  2. With scope:

    feat(azure): add workload identity support
    
    Signed-off-by: Jane Doe <jdoe@example.com>
    Commit-Message-Assisted-by: Claude (via Claude Code)
    
  3. Multi-paragraph with footers:

    fix: prevent racing of requests
    
    Introduce request ID and reference to latest request. Dismiss
    incoming responses other than from latest request.
    
    Remove timeouts which were used to mitigate racing but are
    obsolete now.
    
    Reviewed-by: John Smith
    Refs: #123
    Signed-off-by: Jane Doe <jdoe@example.com>
    Commit-Message-Assisted-by: Claude (via Claude Code)
    

Arguments

  • None. This skill provides formatting rules as context for other skills and workflows.

Quick Checklist

When creating commits:

  • Use conventional commit format: <type>(<scope>): <description>
  • Title under 120 characters
  • Body lines under 140 characters
  • Include Signed-off-by footer
  • Include Commit-Message-Assisted-by: Claude (via Claude Code) footer
  • Validate with make run-gitlint if available
  • Use "!" or BREAKING CHANGE for breaking changes

Reference

Conventional Commits Specification: https://www.conventionalcommits.org/en/v1.0.0/#specification

Suggest Reviewers Helper

This skill provides a Python helper script that analyzes git blame data for the /git:suggest-reviewers command. The script handles the complex task of identifying which lines were changed and who authored the original code.

When to Use This Skill

Use this skill when implementing the /git:suggest-reviewers command. The helper script should be invoked during Step 3 of the command implementation (analyzing git blame for changed lines).

DO NOT implement git blame analysis manually - always use the provided analyze_blame.py script.

Prerequisites

  • Python 3.6 or higher
  • Git repository with commit history
  • Git CLI available in PATH

Helper Script: analyze_blame.py

The analyze_blame.py script automates the complex process of:

  1. Parsing git diff output to identify specific line ranges that were modified
  2. Running git blame on only the changed line ranges (not entire files)
  3. Extracting and aggregating author information with statistics
  4. Filtering out bot accounts automatically

Usage

For uncommitted changes:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py \
  --mode uncommitted \
  --file path/to/file1.go \
  --file path/to/file2.py \
  --output json

For committed changes on a feature branch:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py \
  --mode committed \
  --base-branch main \
  --file path/to/file1.go \
  --file path/to/file2.py \
  --output json

Parameters

  • --mode: Required. Either uncommitted or committed

    • uncommitted: Analyzes unstaged/staged changes against HEAD
    • committed: Analyzes committed changes against a base branch
  • --base-branch: Required when mode is committed. The base branch to compare against (e.g., main, master)

  • --file: Can be specified multiple times. Each file to analyze for blame information. Only changed files should be passed.

  • --output: Output format. Default is json. Options:

    • json: Machine-readable JSON output
    • text: Human-readable text output

Output Format (JSON)

{
  "Author Name": {
    "line_count": 45,
    "most_recent_date": "2024-10-15T14:23:10",
    "files": ["file1.go", "file2.go"],
    "email": "author@example.com"
  },
  "Another Author": {
    "line_count": 23,
    "most_recent_date": "2024-09-20T09:15:33",
    "files": ["file3.py"],
    "email": "another@example.com"
  }
}

Output Fields

  • line_count: Total number of modified lines authored by this person
  • most_recent_date: ISO 8601 timestamp of their most recent contribution to the changed code
  • files: Array of files where this author has contributions in the changed lines
  • email: Author's email address from git commits

Bot Filtering

The script automatically filters out common bot accounts:

  • GitHub bots (e.g., dependabot[bot], renovate[bot])
  • CI bots (e.g., openshift-ci-robot, k8s-ci-robot)
  • Generic bot patterns (any name containing [bot] or ending in -bot)

Implementation Steps

Step 1: Collect changed files

Before invoking the script, collect the list of changed files based on the scenario:

Uncommitted changes:

# Get staged and unstaged files
files=$(git diff --name-only --diff-filter=d HEAD)
files+=" $(git diff --name-only --diff-filter=d --cached)"

Committed changes:

# Get files changed from base branch
files=$(git diff --name-only --diff-filter=d ${base_branch}...HEAD)

Step 2: Invoke the script

Build the command with the appropriate mode and all changed files:

# Start building the command
cmd="python3 ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py"

# Add mode
if [ "$has_uncommitted" = true ] || [ "$on_base_branch" = true ]; then
  cmd="$cmd --mode uncommitted"
else
  cmd="$cmd --mode committed --base-branch $base_branch"
fi

# Add each file
for file in $files; do
  cmd="$cmd --file $file"
done

# Add output format
cmd="$cmd --output json"

# Execute and capture JSON output
blame_data=$($cmd)

Step 3: Parse the output

The JSON output can be parsed using Python, jq, or any JSON parser:

# Example using jq to get top contributor
echo "$blame_data" | jq -r 'to_entries | sort_by(-.value.line_count) | .[0].key'

# Example using Python
python3 << EOF
import json
import sys

data = json.loads('''$blame_data''')

# Sort by line count
sorted_authors = sorted(data.items(), key=lambda x: x[1]['line_count'], reverse=True)

for author, stats in sorted_authors:
    print(f"{author}: {stats['line_count']} lines, last modified {stats['most_recent_date']}")
EOF

Step 4: Combine with OWNERS data

After getting blame data, merge it with OWNERS file information to produce the final ranked list of reviewers.

Error Handling

No changed files

If no files are passed to the script:

Error: No files specified. Use --file option at least once.

Resolution: Ensure you've detected changed files (via git diff --name-only) before invoking the script.

Invalid mode

If an invalid mode is specified:

Error: Invalid mode 'invalid'. Must be 'uncommitted' or 'committed'.

Resolution: Use either --mode uncommitted or --mode committed.

Missing base branch in committed mode

If --mode committed is used without --base-branch:

Error: --base-branch is required when mode is 'committed'.

Resolution: Provide the base branch: --base-branch main

File not in repository

If a specified file is not tracked by git:

Warning: File 'path/to/file' is not tracked by git, skipping.

Resolution: This is a warning and can be safely ignored. The script will skip untracked files.

No blame data found

If git blame returns no data for any files:

{}

Resolution: This can happen if:

  • All changed files are newly created (no blame history)
  • All changes are in binary files
  • Git blame is unable to run

In this case, fall back to OWNERS-only suggestions.

Examples

Example 1: Analyze uncommitted changes

$ python3 analyze_blame.py --mode uncommitted --file src/main.go --file src/utils.go --output json
{
  "Alice Developer": {
    "line_count": 45,
    "most_recent_date": "2024-10-15T14:23:10",
    "files": ["src/main.go", "src/utils.go"],
    "email": "alice@example.com"
  },
  "Bob Engineer": {
    "line_count": 12,
    "most_recent_date": "2024-09-20T09:15:33",
    "files": ["src/main.go"],
    "email": "bob@example.com"
  }
}

Example 2: Analyze committed changes on feature branch

$ python3 analyze_blame.py --mode committed --base-branch main --file pkg/controller/manager.go --output json
{
  "Charlie Contributor": {
    "line_count": 78,
    "most_recent_date": "2024-10-01T11:42:55",
    "files": ["pkg/controller/manager.go"],
    "email": "charlie@example.com"
  }
}

Example 3: Text output format

$ python3 analyze_blame.py --mode uncommitted --file README.md --output text

Blame Analysis Results:
=======================

Alice Developer (alice@example.com)
  Lines: 23
  Most recent: 2024-10-15T14:23:10
  Files: README.md

Bob Engineer (bob@example.com)
  Lines: 5
  Most recent: 2024-08-12T16:30:21
  Files: README.md

Example 4: Multiple files with mixed results

$ python3 analyze_blame.py --mode committed --base-branch release-4.15 \
    --file vendor/k8s.io/client-go/kubernetes/clientset.go \
    --file pkg/controller/node.go \
    --file docs/README.md \
    --output json
{
  "Diana Developer": {
    "line_count": 156,
    "most_recent_date": "2024-09-28T13:15:42",
    "files": ["vendor/k8s.io/client-go/kubernetes/clientset.go", "pkg/controller/node.go"],
    "email": "diana@example.com"
  },
  "Eve Technical Writer": {
    "line_count": 34,
    "most_recent_date": "2024-10-10T10:22:18",
    "files": ["docs/README.md"],
    "email": "eve@example.com"
  }
}

Technical Details

How the script works

  1. Determine diff range: Based on mode, calculates what to compare:

    • uncommitted: Compares working directory against HEAD
    • committed: Compares HEAD against base branch
  2. Parse diff output: Runs git diff with unified format to identify:

    • Which files changed
    • Which line ranges were added/modified
    • Ignores deleted lines (can't blame what doesn't exist)
  3. Run git blame: For each file and line range:

    • Runs git blame -L start,end --line-porcelain file
    • Parses porcelain format to extract author, email, and timestamp
    • Aggregates data across all changed lines
  4. Filter and aggregate:

    • Removes bot accounts
    • Groups by author name
    • Counts total lines per author
    • Tracks most recent contribution date
    • Lists all files each author contributed to
  5. Output results: Formats as JSON or text based on --output parameter

Performance considerations

  • Only blames changed line ranges, not entire files (much faster for small changes to large files)
  • Processes files in parallel when possible
  • Caches git commands where appropriate
  • Skips binary files automatically

Limitations

  • Does not handle file renames/moves (treats as delete + add)
  • Bot filtering is based on common patterns; custom bots may not be filtered
  • Requires git history; newly initialized repos may not have useful data
  • Does not consider commit message content or PR review history

See Also

Commands 10

Name

git:backport

Synopsis

/git:backport <commit> <branch1> [branch2...] [--new-branch|-b]

Description

The git:backport command helps backport a commit to multiple branches. It automates the process of cherry-picking a commit to one or more target branches, with optional support for creating new branches for each backport (useful for creating pull requests).

This command provides:

  • Automated commit backporting to one or multiple branches
  • Validation of commit and branch existence
  • Safe state management (saves and restores current branch)
  • Conflict detection and user-guided resolution
  • Optional new branch creation for PR workflows
  • Support for branches with or without remote tracking

Implementation

The command executes the following workflow:

  1. Validates inputs:

    • Checks that at least 2 arguments are provided (commit + at least one branch)
    • Parses the --new-branch or -b flag if present
    • Verifies the commit exists using git cat-file -t <commit>
    • Shows commit details: git log -1 --oneline <commit>
    • Filters out flag arguments and verifies all remaining target branches exist
  2. ASK FOR USER PERMISSION:

    • IMPORTANT: After validating inputs, you MUST present the complete backport plan to the user and ask for explicit permission to proceed
    • Show what will happen: which branches will be checked out, which new branches will be created, and that commits will be made
    • Wait for user confirmation before proceeding with any git operations
    • Example: "I'm going to checkout release/v1.35, pull latest changes, create branch backport-abc1234-to-release/v1.35, cherry-pick the commit, then repeat for release/v1.34. This will create new branches and commits. Should I proceed?"
  3. Saves current state (only after user permission):

    • Records the current branch: git branch --show-current
    • Checks for uncommitted changes: git status --porcelain
    • If there are uncommitted changes, warns the user and stops
  4. For each target branch (only after user permission):

    • Shows which target branch is being worked on
    • Checks out the target branch: git checkout <branch>
    • Checks if the branch tracks a remote branch: git rev-parse --abbrev-ref <branch>@{upstream}
    • If the branch tracks a remote branch:
      • Pulls latest changes to ensure it's up to date: git pull
    • If the branch doesn't track a remote branch:
      • Skips pulling and informs the user the branch is local-only
    • If --new-branch flag is set:
      • Creates a new branch for the backport: git checkout -b backport-<commit-short-hash>-to-<branch>
        • Uses the short commit hash (first 7 chars) in the branch name
        • Example: backport-abc1234-to-release-1.0
    • Attempts to cherry-pick: git cherry-pick <commit>
    • If conflicts occur:
      • Shows the conflicting files: git status
      • Shows the conflicts: git diff
      • STOPS and asks the user to resolve conflicts
      • Tells them to run git cherry-pick --continue when done, or git cherry-pick --abort to skip
      • Asks if they want to continue to the next branch or abort the entire operation
    • If successful:
      • Shows success message with the new commit hash
      • If a new branch was created, shows the branch name
      • Continues to next branch
  5. Restores original state:

    • Returns to the original branch: git checkout <original-branch>
    • Shows final summary of all backports:
      • Lists successful backports with their branch names (if --new-branch was used)
      • Lists failed backports
      • If --new-branch was used, reminds user they can now create PRs from the new branches

The command is interactive and waits for user input when conflicts occur and REQUIRES USER PERMISSION before executing any git operations. It tracks success/failure for each branch and provides a comprehensive summary at the end.

Return Value

  • Claude agent text:
    • Success summary showing which branches were successfully backported
    • List of any failed backports
    • New branch names (if --new-branch flag was used)
    • Instructions for next steps (e.g., creating PRs from new branches)

Examples

  1. Basic backport to a single branch:

    /git:backport abc1234 release-1.0
    

    Cherry-picks commit abc1234 directly to the release-1.0 branch.

  2. Backport to multiple branches:

    /git:backport abc1234 release-1.0 release-1.1 release-1.2
    

    Cherry-picks commit abc1234 to three different release branches.

  3. Backport with new branch creation (for PRs):

    /git:backport abc1234 release-1.0 release-1.1 --new-branch
    

    Creates new branches backport-abc1234-to-release-1.0 and backport-abc1234-to-release-1.1, each containing the cherry-picked commit. These branches can then be used to create pull requests.

  4. Using short flag syntax:

    /git:backport abc1234 main -b
    

    Same as --new-branch, creates a new branch backport-abc1234-to-main.

Arguments

  • $1: Commit hash or reference to backport (required)
  • $2+: Target branch names to backport to (space-separated, at least one required)
  • --new-branch or -b: Create a new branch from each target branch before cherry-picking (optional flag)

Name

git:bisect

Synopsis

/git:bisect                       # Fully interactive - will ask for all inputs
/git:bisect [good-commit] [bad-commit]  # With commit references

Description

The git:bisect command is an interactive git bisect assistant that helps find the exact commit that introduced a specific change (bug, behavior change, feature, performance regression, etc.) using binary search.

What This Command Does:

  1. Guides you through setup - Validates commits, checks for conflicts
  2. Presents commits for evaluation - Shows relevant info about each commit
  3. Learns from your decisions - Detects patterns in your choices
  4. Can automate - If it understands your criterion, it can evaluate automatically (with your permission)
  5. Reports the result - Shows the culprit commit with full details

Terminology

Git bisect uses confusing terms. This command uses clearer labels:

What You SeeGit TermMeaning
"Change IS in the code"badThe change you're looking for EXISTS in this commit
"Change is NOT in the code"goodThe change you're looking for does NOT exist yet

Never use "good" or "bad" alone - always explain what they mean in context.

Workflow

1. Provide (or select) reference commits
         ↓
2. Describe what change you're looking for
         ↓
3. [If criterion is clear] Confirm understanding → Choose manual/auto
         ↓
4. Evaluate commits (manually or automatically)
         ↓
5. Receive final report with culprit commit
         ↓
6. Clean up (git bisect reset)

Commands During Bisect

At any point during the bisect, you can:

  • "show diff" or "more details" - See the full diff for the current commit
  • "skip" - Skip a commit that cannot be tested (won't build, etc.)
  • "abort" - Cancel the bisect and return to your original branch
  • "automate" - Ask to enable automation (if pattern detected)

Tips

  • You can test the current state by building/running your project between steps
  • Use skip if a commit cannot be tested (build failure, unrelated issue)
  • The process uses binary search: ~log₂(N) steps for N commits
  • You can abort at any time; the session will be cleanly terminated

Implementation

Arguments provided: $ARGUMENTS

Parse arguments:

  • If two arguments: first = commit where change is NOT present, second = commit where change IS present
  • If one argument: ask which one it represents
  • If no arguments: proceed to interactive mode

Critical Rules

Rule 1: Never decide without asking first

You may NEVER execute git bisect good or git bisect bad without explicit user confirmation. Even if you're 100% certain, you MUST ask first. No exceptions.

Rule 2: Early criterion detection (≥70% confidence)

If the user describes a criterion that you can verify programmatically (e.g., "when dependency X was updated to version > Y"), and you have ≥70% confidence you understand the exact criterion:

  1. BEFORE evaluating any commit, present your understanding with maximum precision:

    "Based on your description, I believe you're looking for: [exact criterion with specific details]

    To verify this, I would check: [specific file/command/method]

    Is this correct?"

  2. Wait for user response. Then:

    • If user confirms the criterion is correct, ask:

      "Would you like me to automatically evaluate commits based on this criterion? I will show each decision as I make it."

      • If user says yes → Enable automation mode
      • If user says no → Continue in manual mode (ask for each commit)
    • If user says the criterion is wrong:

      • Say: "I understand. Please clarify what you're looking for."
      • Reset your understanding completely
      • Enter manual mode
      • Continue learning from user responses
Rule 3: Learning from manual decisions

If you don't have ≥70% confidence initially, or after a criterion reset:

  1. Present commit info and ask the user for their verdict
  2. Analyze patterns in their decisions (files, authors, keywords)
  3. When confidence reaches ≥70%, present your understanding and follow Rule 2
Rule 4: Automation flow

When automation is enabled (user explicitly said yes):

  1. For each commit:
    • Show the commit being evaluated
    • Show your decision and the reasoning
    • Execute git bisect good or git bisect bad
  2. If any commit doesn't clearly match the criterion, STOP and ask the user
  3. Continue until bisect completes

Phase 1: Initialization

Step 1.1: Check for Existing Bisect Session

Run git bisect log to check if a bisect is in progress.

If bisect IS in progress:

  1. Show the current state: how many steps done, current commit
  2. Ask the user:
    • Continue: Resume the existing session
    • Abort: Run git bisect reset and optionally start fresh
    • View details: Show full bisect log before deciding

If NO bisect in progress: Continue to Step 1.2

Step 1.2: Check for Uncommitted Changes

Run git status --porcelain to check for uncommitted changes.

If there are uncommitted changes:

  1. Warn: "You have uncommitted changes. Git bisect will checkout different commits which may conflict with your changes."
  2. Offer options:
    • Stash changes: Run git stash push -m "Pre-bisect stash"
    • Proceed anyway: Continue (user accepts the risk)
    • Abort: Stop to handle manually
Step 1.3: Get Reference Commits

If commits were provided as arguments:

  1. Validate using git rev-parse <commit>
  2. Show what each commit represents (run git log -1 --format="%h %s" <commit>)
  3. Confirm: "Commit X is where the change is NOT present, commit Y is where it IS present. Correct?"

If commits were NOT provided:

  1. Show recent history: git log --oneline -20
  2. Ask: "Which commit is known to NOT have the change you're looking for? (This will be the 'good' starting point)"
  3. Ask: "Which commit IS known to have the change? (This will be the 'bad' starting point)"

Validate the relationship:

  • The "good" commit (without change) should be an ancestor of the "bad" commit (with change)
  • If they appear reversed, explain and offer to swap
Step 1.4: Understand the Search Criterion

Ask the user:

What change are you looking for?

Please describe:

  • What behavior or code changed?
  • How can you determine if a commit has or doesn't have this change?
  • Is there a specific file, function, or behavior to check?

Store this description for analysis.

Step 1.5: Early Criterion Detection (CRITICAL)

After the user describes the change, analyze their response:

If you have ≥70% confidence that you understand a verifiable criterion:

  1. Present your understanding with maximum precision:

    "Based on your description, I believe you're looking for: [exact criterion]

    To verify this, I would check: [specific method]

    Is this correct?"

  2. WAIT for user response before proceeding.

  3. If user confirms:

    "Would you like me to automatically evaluate commits based on this criterion? I will show each decision as I make it."

    • If yes → Set automation mode = true
    • If no → Set automation mode = false (manual mode)
  4. If user says criterion is wrong:

    • Ask for clarification
    • Set automation mode = false
    • Proceed to bisect in manual mode

Only proceed to Step 1.6 after this interaction is complete.

Step 1.6: Start Bisect

Execute:

git bisect start
git bisect bad <commit-with-change>
git bisect good <commit-without-change>

Parse the output to show:

  • Number of revisions to test
  • Estimated number of steps (approximately log2 of revisions)
  • The first commit to test

Phase 2: Evaluation Loop

Internal State to Track

Maintain a session log throughout the bisect:

## Session Log

**Search criterion**: [user's description]
**Detected pattern**: [none yet / description]
**Confidence level**: [0-100%]
**Automation enabled**: [no / yes]

| Step | Commit | Files Changed | Verdict | Observation |
|------|--------|---------------|---------|-------------|
For Each Commit
Step 2.1: Present Commit Information

Display:

═══════════════════════════════════════════════════════════
TESTING COMMIT [step X of ~Y estimated]
═══════════════════════════════════════════════════════════

Commit:  [short hash]
Author:  [author name]
Date:    [date]
Message: [subject line]

Files Changed:
[output of: git show --stat --format="" HEAD]

Summary: [X files changed, Y insertions(+), Z deletions(-)]
═══════════════════════════════════════════════════════════
Step 2.2: Evaluate Commit (depends on mode)

If AUTOMATION MODE is enabled:

  1. Verify the criterion for this commit (run the check you described to user)
  2. Show the result:
    Commit [hash]: Checking [criterion]...
    Result: [what you found]
    Decision: Change [IS / is NOT] in the code → marking as [bad/good]
    
  3. Execute git bisect bad or git bisect good
  4. If the result is unclear or doesn't match the criterion cleanly, STOP and ask user

If MANUAL MODE (automation not enabled):

Ask the user:

Is the change you're looking for present in this commit?

[1] Change IS in the code (will mark as 'bad')
[2] Change is NOT in the code (will mark as 'good')
[3] Cannot test this commit (skip)
[4] Show more details (diff, full message)
[5] Abort bisect

If in manual mode and confidence reaches ≥70%:

Before showing options, present your understanding:

I've noticed a pattern: [description of what you've observed]

Based on this, I believe the change [IS / is NOT] in this commit.

Is this the criterion you're using? If so, would you like me to automate?

[1] Yes, that's correct - please automate
[2] Yes, that's correct - but I'll decide manually
[3] No, that's not what I'm looking for
[4] Show more details first

If user chooses [1] → Enable automation mode If user chooses [2] → Stay in manual mode but show suggestions If user chooses [3] → Reset pattern analysis, continue manual

Step 2.3: Process Response

Based on user response:

ResponseAction
Change IS in codeRun git bisect bad, record in log
Change NOT in codeRun git bisect good, record in log
SkipRun git bisect skip, note why in log
Show detailsDisplay requested info, ask again
AbortConfirm, then run git bisect reset
Step 2.4: Update Session Log

After each decision, update the internal log with:

  • Commit hash
  • Key files changed
  • User's verdict
  • Any observations about patterns
Step 2.5: Pattern Analysis (Manual Mode Only)

When in manual mode, after each user decision:

  1. Analyze correlations:

    • File patterns: Do "change present" commits touch specific files?
    • Author patterns: Is a specific author correlated?
    • Message patterns: Are there specific keywords?
  2. Update confidence based on how well patterns predict user decisions

  3. When confidence reaches ≥70%:

    • Present your understanding in Step 2.2 (as described above)
    • This may result in switching to automation mode if user accepts

Phase 3: Completion

Detecting Completion

Git bisect outputs "X is the first bad commit" when complete. Watch for this phrase.

Final Report

When bisect completes, present:

═══════════════════════════════════════════════════════════
BISECT COMPLETE - CULPRIT FOUND
═══════════════════════════════════════════════════════════

THE COMMIT THAT INTRODUCED THE CHANGE
─────────────────────────────────────

Commit:  [full hash]
Author:  [author name] <[email]>
Date:    [full date]

Message:
[full commit message]

Files Changed:
[git show --stat --format="" <hash>]

CHANGE SUMMARY
─────────────────────────────────────

Based on your search criterion: "[user's original description]"

This commit appears to have introduced the change by:
[Analysis of what changed in this commit that matches the criterion]

EVALUATION HISTORY
─────────────────────────────────────

| Step | Commit  | Verdict              | Key Files        |
|------|---------|----------------------|------------------|
| 1    | abc1234 | Change present       | src/main.rs      |
| 2    | def5678 | Change NOT present   | tests/test.rs    |
| ...  | ...     | ...                  | ...              |

SUGGESTED NEXT STEPS
─────────────────────────────────────

1. View full diff: git show [hash]
2. Compare with parent: git diff [hash]^..[hash]
3. Revert this commit: git revert [hash]
4. Blame specific file: git blame [file] | grep [hash]

═══════════════════════════════════════════════════════════
Cleanup

Ask:

"The bisect session is complete. Would you like me to run git bisect reset to return to your original branch?"

If yes, run git bisect reset and confirm the branch returned to.


Error Handling

Common Errors and Solutions
ErrorSolution
"You need to start by 'git bisect start'"Bisect was interrupted; restart the process
"Bad rev input: X"Invalid commit reference; ask for correction and show recent commits
"Some good revs are not ancestors of the bad rev"Commits are in wrong order; explain and offer to swap
Merge conflict during checkoutSuggest git bisect skip for this commit
"Cannot bisect on a detached HEAD"This shouldn't happen normally; offer to reset
Abort Handling

If user requests abort at any point:

  1. Confirm: "Are you sure you want to abort? The bisect progress will be lost."
  2. If confirmed: Run git bisect reset
  3. Show the branch/commit returned to
  4. Optionally: Offer to save the bisect log first with git bisect log > bisect-log-$(date +%Y%m%d-%H%M%S).txt

Examples

  1. Fully interactive - no arguments:

    /git:bisect
    

    Will show recent history and ask you to select commits.

  2. With commit references:

    /git:bisect v1.28.0 HEAD
    

    Uses tag v1.28.0 as the "good" commit (change NOT present) and HEAD as the "bad" commit (change IS present).

  3. With commit hashes:

    /git:bisect abc1234 def5678
    
  4. Mixed references:

    /git:bisect v1.0.0 main
    

Return Value

  • Final Report: A comprehensive report showing:

    • The culprit commit (full hash, author, date, message)
    • Files changed in that commit
    • Analysis of how the commit matches the search criterion
    • Evaluation history table
    • Suggested next steps (view diff, revert, blame)
  • Session cleanup: Offers to run git bisect reset to return to original branch

Arguments

  • $1 [good-commit] (optional): A commit reference (hash, tag, branch) where the change is NOT present. This is the older, "known good" state.
  • $2 [bad-commit] (optional): A commit reference where the change IS present. This is the newer state that contains the change you're looking for.

Notes:

  • If no arguments are provided, the command will show recent history and ask you to select commits
  • If only one argument is provided, the command will ask which one it represents (good or bad)
  • Commit references can be: hashes, tags, branch names, HEAD, HEAD~N, etc.

Name

git:branch-cleanup

Synopsis

/git:branch-cleanup [--dry-run] [--merged-only] [--remote]

Description

The git:branch-cleanup command identifies and removes old, defunct, or merged branches from your local repository (and optionally from remote). It helps maintain a clean repository by removing branches that are no longer needed, such as:

  • Branches that have been merged into the main branch
  • Branches that no longer exist on the remote
  • Stale feature branches from completed work

The command performs safety checks to prevent deletion of:

  • The current branch
  • Protected branches (main, master, develop, etc.)
  • Branches with unmerged commits (unless explicitly overridden)

The spec sections is inspired by https://man7.org/linux/man-pages/man7/man-pages.7.html#top_of_page

Implementation

The command should follow these steps:

  1. Identify Main Branch

    • Detect the primary branch (main, master, etc.)
    • Use git symbolic-ref refs/remotes/origin/HEAD or git branch -r to determine
  2. Gather Branch Information

    • List all local branches: git branch
    • Get current branch: git branch --show-current
    • Identify merged branches using multi-layered detection:
      • Standard merge: git branch --merged <main-branch>
      • Merge commit messages: git log <main-branch> --merges --oneline
      • Content comparison: git diff <main-branch>...<branch> --quiet
      • Cherry-pick detection: git cherry <main-branch> <branch>
    • Check remote tracking: git branch -vv
    • Find remote-deleted branches: git remote prune origin --dry-run
  3. Categorize Branches

    • Merged branches: Detected via one of these methods:
      • Standard: Commits directly in main branch history
      • Merge commit: Found in main's merge commit messages
      • Content-identical: All changes present in main (rebased/cherry-picked)
      • Cherry-picked: All commits have equivalents in main
    • Gone branches: Remote tracking branch no longer exists
    • Stale branches: Last commit older than threshold (e.g., 3 months)
    • Protected branches: main, master, develop, release/, hotfix/
  4. Present Analysis to User

    • Show categorized list of branches with:
      • Branch name
      • Last commit date
      • Merge status
      • Remote tracking status
      • Number of commits ahead/behind
    • Recommend branches safe to delete
  5. Confirm Deletion

    • Ask user to confirm which branches to delete
    • Present options: all merged, all gone, specific branches, or custom selection
    • If --dry-run flag is present, only show what would be deleted
  6. Delete Branches

    • Local deletion: git branch -d <branch> (merged) or git branch -D <branch> (force)
    • Remote deletion (if --remote flag): git push origin --delete <branch>
    • Prune remote references: git remote prune origin
  7. Report Results

    • List deleted branches
    • Show any errors or branches that couldn't be deleted
    • Provide summary statistics

Implementation logic:

# Determine main branch
main_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$main_branch" ]; then
  main_branch="main"  # fallback
fi

# Get current branch
current_branch=$(git branch --show-current)

# Multi-layered merge detection function
# Returns: "merged:<method>" or "not-merged"
check_if_merged() {
    local branch=$1
    local main_branch=$2
    # Escape for grep ERE: ] [ \ . ^ $ * + ? ( ) { } |
    local branch_escaped=$(printf '%s\n' "$branch" | sed -e 's/[][\\.^$*+?(){}|]/\\&/g')

    # Method 1: Standard merge check (commits in main history)
    if git branch --merged "$main_branch" | grep -q "^[* ]*${branch_escaped}$"; then
        echo "merged:standard"
        return 0
    fi

    # Method 2: Merge-commit message heuristic (requires branch mention)
    # Matches examples: "Merge branch 'X'", "Merge pull request ... from org/X"
    # Note: Squash merges are not --merges; those are covered by Method 3 (content-identical).
    local branch_basename=${branch##*/}
    local branch_basename_escaped
    branch_basename_escaped=$(printf '%s\n' "$branch_basename" | sed -e 's/[][\\.^$*+?(){}|]/\\&/g')
    if git log "$main_branch" --merges --oneline \
      | grep -qiE "merge.*(branch[[:space:]]+'${branch_escaped}'|\b${branch_escaped}\b|from[[:space:]]+[^[:space:]]*/${branch_basename_escaped})"; then
        echo "merged:merge-commit"
        return 0
    fi

    # Method 3: Content comparison (handles rebased/cherry-picked branches)
    # Uses three-dot syntax (merge-base comparison) to detect content-identical branches
    # If diff is empty, all content is in main even if commit hashes differ
    # Note: 2>/dev/null suppresses errors for edge cases (no common ancestor, invalid branch)
    if git diff --quiet "$main_branch"..."$branch" 2>/dev/null; then
        echo "merged:content-identical"
        return 0
    fi

    # Method 4: Cherry-pick detection (all commits have equivalents in main)
    # Commits prefixed with '-' have equivalent patches in main
    # Note: Detects patch equivalence, not necessarily commits reachable from main
    # May have rare false positives with coincidentally similar commits
    local unmerged=$(git cherry "$main_branch" "$branch" 2>/dev/null | grep -c '^+')
    if [ "$unmerged" -eq 0 ]; then
        echo "merged:cherry-picked"
        return 0
    fi

    echo "not-merged"
    return 1
}

# Find all merged branches with detection method
for branch in $(git branch | grep -v "^\*" | sed 's/^[ ]*//'); do
    if [ "$branch" != "$main_branch" ]; then
        merge_status=$(check_if_merged "$branch" "$main_branch")
        if [[ "$merge_status" == merged:* ]]; then
            method=${merge_status#merged:}
            echo "$branch|$method"
        fi
    fi
done

# Find branches with deleted remotes ("gone")
git branch -vv | grep ': gone]' | awk '{print $1}'

# Find stale branches (older than 3 months)
git for-each-ref --sort=-committerdate --format='%(refname:short)|%(committerdate:iso)|%(upstream:track)' refs/heads/

# Delete local branch (merged)
git branch -d <branch-name>

# Delete local branch (force)
git branch -D <branch-name>

# Delete remote branch
git push origin --delete <branch-name>

# Prune remote references
git remote prune origin

Return Value

  • Claude agent text: Analysis and results including:
    • List of branches categorized by status (merged, gone, stale)
    • Recommendation for which branches are safe to delete
    • Confirmation prompt for user approval
    • Summary of deleted branches and any errors
    • Statistics (e.g., "Deleted 5 branches, freed X MB")

Examples

  1. Basic usage (interactive):

    /git:branch-cleanup
    

    Output:

    Analyzing branches in repository...
    
    Main branch: main
    Current branch: feature/new-api
    
    === Merged Branches (safe to delete) ===
    feature/bug-fix-123        Merged (standard) - 2 weeks ago
    feature/update-deps        Merged (merge-commit) - 1 month ago
    feature/rebased-work       Merged (content-identical) - 3 days ago
    
    === Gone Branches (remote deleted) ===
    feature/old-feature        Remote: gone
    hotfix/urgent-fix          Remote: gone
    
    === Stale Branches (no activity > 3 months) ===
    experiment/prototype       Last commit: 4 months ago, not merged
    
    === Protected Branches (will not delete) ===
    main
    develop
    
    Recommendations:
    - Safe to delete: feature/bug-fix-123, feature/update-deps (merged)
      * Note: feature/rebased-work has different commits but identical content (rebased)
    - Safe to delete: feature/old-feature, hotfix/urgent-fix (remote gone)
    - Review needed: experiment/prototype (unmerged, stale)
    
    What would you like to delete?
    
  2. Dry run (preview only):

    /git:branch-cleanup --dry-run
    

    Output:

    [DRY RUN MODE - No changes will be made]
    
    Would delete the following merged branches:
    - feature/bug-fix-123
    - feature/update-deps
    
    Would delete the following gone branches:
    - feature/old-feature
    - hotfix/urgent-fix
    
    Total: 4 branches would be deleted
    
  3. Merged branches only:

    /git:branch-cleanup --merged-only
    

    Output:

    Analyzing merged branches...
    
    Found 3 merged branches:
    - feature/bug-fix-123
    - feature/update-deps
    - feature/ui-improvements
    
    Delete these branches? (y/n)
    
  4. Including remote cleanup:

    /git:branch-cleanup --remote
    

    Output:

    Deleting local and remote branches...
    
    ✓ Deleted local: feature/bug-fix-123
    ✓ Deleted remote: origin/feature/bug-fix-123
    ✓ Deleted local: feature/update-deps
    ✓ Deleted remote: origin/feature/update-deps
    
    Summary: Deleted 2 branches locally and remotely
    

Arguments

  • --dry-run: Preview which branches would be deleted without actually deleting them
  • --merged-only: Only consider branches that have been fully merged into the main branch
  • --remote: Also delete branches from the remote repository (requires push permissions)
  • --force: Force delete branches even if they have unmerged commits (use with caution)
  • --older-than=<days>: Only consider branches with no commits in the last N days (default: 90)

Safety Considerations

  • Never delete: Current branch, main, master, develop, or release/* branches
  • Require confirmation: Always ask user before deleting branches
  • Preserve unmerged work: By default, only delete merged branches unless --force is used
  • Backup suggestion: Recommend creating a backup of unmerged branches before deletion
  • Remote deletion: Only delete remote branches if user explicitly requests with --remote flag

Name

git:cherry-pick-by-patch

Synopsis

/git:cherry-pick-by-patch commit_hash

Description

The /git-cherry-pick-by-patch commit_hash command cherry-picks commit with hash commit_hash into current branch. Rather then doing git cherry-pick commit_hash, the command streams the output of git show commit_hash to patch -p1 --no-backup-if-mismatch, and then commit changes with commit message from commit_hash commit.

Implementation

Pre-requisites

The commit with hash commit_hash must exist. To verify that use:

git show commit_hash

and check if exit code is zero.

Fail, if there is no commit_hash in the current repository checkout.

Cherry-pick commit_hash into current branch

  1. Execute command
    git show commit_hash | patch -p1 --no-backup-if-mismatch
    

and check if exit code is zero. Fail if exit code is not zero.

  1. Find files removed from local checkout by the patch command and execute git rm for them.

  2. Find files added or modified by the patch command and execute git add for them.

  3. Commit changes by git commit command and use commit title and description from commit_hash commit.

Arguments

  • $1 (required): Commit hash (e.g., 902409c0) of commit to cherry-pick.

Name

git:commit-suggest

Synopsis

/git:commit-suggest       # Analyze staged changes
/git:commit-suggest [N]     # Analyze last N commits (1-100)

Description

AI-powered command that analyzes code changes and generates Conventional Commits–style messages.

Modes:

  • Mode 1 (no argument) – Analyze staged changes (git add required)
  • Mode 2 (with N) – Analyze last N commits to rewrite (N=1) or summarize for squash (N≥2)

Use cases:

  • Create standardized commit messages
  • Improve or rewrite existing commits
  • Generate squash messages for PR merges

Difference from /git:summary – That command is read-only, while git:commit-suggest generates actionable commit message suggestions for user review and manual use.

Implementation

The command operates in two modes based on input:

Mode 1 (no argument):

  1. Collect staged changes via git diff --cached
  2. Analyze file paths and code content to identify type (feat/fix/etc.) and scope
  3. Generate 3 commit message suggestions (Recommended, Standard, Minimal)
  4. Display formatted suggestions and prompt user for selection
    • Ask: "Which suggestion would you like to use? (1/2/3 or skip)"
    • Support responses: 1, use option 2, commit with option 3, skip
    • Execute git commit with selected message if user requests

Mode 2 (with N):

  1. Retrieve last N commits using git log
  2. Parse commit messages to extract types, scopes, and descriptions
  3. For N=1: Suggest improved rewrite For N≥2: Merge commits intelligently by type priority (fix > feat > perf > refactor > docs > test > chore)
  4. Generate 3 commit message suggestions (Recommended, Standard, Minimal)
  5. Display formatted suggestions and prompt user for selection
    • Ask: "Which suggestion would you like to use? (1/2/3 or skip)"
    • Support responses: 1, use option 2, amend with option 3, skip
    • Execute git commit --amend (N=1) or squash operation (N≥2) if user requests

Examples

# Generate message for staged files
git add src/auth.ts src/middleware.ts
/git:commit-suggest

# Rewrite last commit message
/git:commit-suggest 1

# Summarize last 5 commits for squash
/git:commit-suggest 5

Return Value

Generates 3 commit message suggestions:

  • Suggestion #1 (Recommended) – Detailed with full body and metadata
  • Suggestion #2 (Standard) – Concise with main points
  • Suggestion #3 (Minimal) – Title and short summary

Each suggestion includes:

  • Conventional Commits message (type(scope): description)
  • Blank line between title and body
  • Optional body text explaining the changes
  • Optional footer (issue refs, co-authors, breaking changes, etc.)

Example:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Suggestion #1 (Recommended)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
feat(auth): add JWT authentication middleware

Implement token-based authentication for API endpoints.
The middleware verifies JWT tokens and extracts user information.

Fixes: #123

Which suggestion would you like to use? (1/2/3 or skip)

Mode 2 Specifics

  • N=1 – Suggest improved rewrite for the last commit
  • N≥2 – Generate unified squash message with footer: Squashed from N commits: + original commit list

Conventional Commits Reference

Format

type(scope): description

[optional body]

[optional footer]

Common Types

  • feat – New feature
  • fix – Bug fix
  • docs – Documentation changes
  • refactor – Code refactoring
  • perf – Performance improvements
  • test – Test additions or modifications
  • build – Build system or dependency changes
  • ci – CI configuration changes
  • chore – Other changes that don't modify src or test files

Scope & Footer Examples

Scope: auth, api, ui, db, deps (indicates affected module)

Footer:

  • Issue refs: Fixes: #123, Closes: #456, Related: #789
  • Breaking changes: BREAKING CHANGE: description
  • Co-authors: Co-authored-by: Name <email@example.com>

Arguments

  • [N] (optional): Number of recent commits to analyze (1-100)
    • If omitted: Analyzes staged changes (Mode 1)
    • If N=1: Suggests improved rewrite for the last commit
    • If N≥2: Generates unified squash message for last N commits

See Also

Name

git:debt-scan

Synopsis

/git:debt-scan

Description

The git:debt-scan command provides a comprehensive analysis of technical debt indicators in the current Git repository. It scans for common code health signals including TODO/FIXME comments, stale branches, large files, uncommitted changes, and recent development activity patterns. This command is designed to give developers quick insights into areas that may need attention without making any modifications to the repository.

It provides essential information for developers including:

  • Count and locations of TODO, FIXME, HACK, and XXX comments
  • Stale branches tracking openshift org remotes that may need cleanup (excludes main, master, develop, release-*, gh-pages, local-only branches, and personal forks)
  • Large git-tracked files that might benefit from refactoring
  • Uncommitted or unstaged changes
  • Recent commit activity trends

The spec sections is inspired by https://man7.org/linux/man-pages/man7/man-pages.7.html#top_of_page

Implementation

  • Executes multiple analysis commands to gather technical debt indicators
  • Searches codebase for technical debt comments (TODO, FIXME, HACK, XXX)
  • Identifies stale branches tracking openshift org GitHub remotes (excludes main, master, develop, release-*, gh-pages, local-only branches, and personal forks)
  • Verifies branches still exist on upstream remote to avoid false positives
  • Finds large git-tracked files that may need refactoring
  • Shows uncommitted changes
  • Analyzes recent commit patterns
  • Formats output for clear readability
  • All operations are read-only with no side effects

Implementation logic:

# Search for technical debt comments
echo "=== Technical Debt Comments ==="
FILE_PATTERNS="*.{js,ts,go,py,java,rb,c,cpp,h,hpp,cs,php,swift,kt}" && for marker in TODO FIXME HACK XXX; do echo "$marker comments: $(grep -r "$marker" --include="$FILE_PATTERNS" . 2>/dev/null | grep -v '.git/' | wc -l | xargs)"; done

# Show top 10 files with most debt comments
echo -e "\n=== Files with Most Debt Comments ==="
grep -r 'TODO\|FIXME\|HACK\|XXX' --include="*.{js,ts,go,py,java,rb,c,cpp,h,hpp,cs,php,swift,kt}" . 2>/dev/null | grep -v '.git/' | cut -d: -f1 | sort | uniq -c | sort -rn | head -10

# Check for stale branches on openshift remotes (excluding main, master, release branches)
echo -e "\n=== Stale Branches (not updated in 30+ days) ===" && bash -c 'OPENSHIFT_REMOTES=$(git remote -v | grep -E "github\.com[:/]openshift/" | grep fetch | awk "{print \$1}" | sort -u); if [ -z "$OPENSHIFT_REMOTES" ]; then echo "(No openshift GitHub remotes found)"; else for remote in $OPENSHIFT_REMOTES; do git ls-remote --heads "$remote" | awk "{print \$2}" | sed "s|refs/heads/||" | grep -vE "^(main|master|develop|release-.*|gh-pages)$" | while read branch; do commit_info=$(git log -1 --format="%cr|%an" "$remote/$branch" 2>/dev/null || echo ""); if [ -n "$commit_info" ]; then date=$(echo "$commit_info" | cut -d"|" -f1); author=$(echo "$commit_info" | cut -d"|" -f2); echo "$date" | grep -qE "years? ago|months? ago|[4-9] weeks ago|[0-9]{2,} weeks ago" && echo "$branch - Last commit: $date by $author"; fi; done | head -10; done; fi'

# Find large files (only git-tracked files)
echo -e "\n=== Large Files (>1MB, tracked by git) ==="
git ls-files | xargs ls -lh 2>/dev/null | awk '$5 ~ /M$/ && $5+0 > 1 {print $9 " - " $5}' | head -10

# Check uncommitted changes
echo -e "\n=== Uncommitted Changes ==="
git status --porcelain | head -20

# Recent commit activity
echo -e "\n=== Commit Activity ===" && echo "Commits in last week: $(git log --since='1 week ago' --oneline 2>/dev/null | wc -l | xargs)" && echo "Commits in last month: $(git log --since='1 month ago' --oneline 2>/dev/null | wc -l | xargs)" && bash -c 'count=$(git log --since="30 days ago" --oneline 2>/dev/null | wc -l | xargs); if command -v bc >/dev/null 2>&1; then avg=$(echo "scale=1; $count / 30" | bc 2>/dev/null); echo "Average commits per day (last 30 days): ${avg:-0}"; else echo "Average commits per day (last 30 days): ~$((count / 30))"; fi'

Return Value

  • Claude agent text: Formatted analysis including:
    • Count of technical debt comments by type (TODO, FIXME, HACK, XXX)
    • List of files with the most debt comments
    • List of stale branches (30+ days old)
    • List of large files (>1MB) tracked by git that may need refactoring
    • Summary of uncommitted/unstaged changes
    • Recent commit activity statistics

Examples

  1. Clean repository with minimal debt:

    /git:debt-scan
    

    Output:

    === Technical Debt Comments ===
    TODO comments: 5
    FIXME comments: 1
    HACK comments: 0
    XXX comments: 0
    
    === Files with Most Debt Comments ===
       3 ./src/api/users.ts
       2 ./src/utils/helpers.js
       1 ./tests/integration.test.ts
    
    === Stale Branches (not updated in 30+ days) ===
    feature/old-experiment - Last commit: 3 months ago by Alice
    bugfix/minor-issue - Last commit: 2 months ago by Bob
    
    === Large Files (>1MB, tracked by git) ===
    data/seed.json - 2.1M
    
    === Uncommitted Changes ===
    
    
    === Commit Activity ===
    Commits in last week: 12
    Commits in last month: 48
    Average commits per day (last 30 days): 1.6
    
  2. Repository with technical debt to address:

    /git:debt-scan
    

    Output:

    === Technical Debt Comments ===
    TODO comments: 47
    FIXME comments: 23
    HACK comments: 8
    XXX comments: 5
    
    === Files with Most Debt Comments ===
      12 ./src/legacy/payment-processor.js
       9 ./src/controllers/auth.ts
       7 ./src/services/notifications.py
       5 ./src/utils/data-transformer.go
       4 ./tests/e2e/checkout.test.js
    
    === Stale Branches (not updated in 30+ days) ===
    feature/refactor-database - Last commit: 5 months ago by Carol
    feature/new-ui - Last commit: 4 months ago by Dave
    bugfix/memory-leak - Last commit: 6 weeks ago by Eve
    
    === Large Files (>1MB, tracked by git) ===
    src/legacy/monolith.js - 5.3M
    dist/bundle.min.js - 3.2M
    data/migrations.sql - 2.8M
    
    === Uncommitted Changes ===
     M src/api/routes.ts
    ?? temp/debug-logs.txt
    ?? scripts/experimental.sh
    
    === Commit Activity ===
    Commits in last week: 3
    Commits in last month: 15
    Average commits per day (last 30 days): 0.5
    
  3. Active development repository:

    /git:debt-scan
    

    Output:

    === Technical Debt Comments ===
    TODO comments: 18
    FIXME comments: 4
    HACK comments: 2
    XXX comments: 0
    
    === Files with Most Debt Comments ===
       6 ./src/features/new-feature.ts
       4 ./src/api/v2/endpoints.go
       3 ./tests/unit/service.test.js
    
    === Stale Branches (not updated in 30+ days) ===
    (no stale branches found)
    
    === Large Files (>1MB, tracked by git) ===
    docs/api-reference.pdf - 1.2M
    
    === Uncommitted Changes ===
     M src/features/new-feature.ts
     M tests/unit/service.test.js
    
    === Commit Activity ===
    Commits in last week: 28
    Commits in last month: 89
    Average commits per day (last 30 days): 3.0
    

Interpretation Guide

Technical Debt Comments:

  • 0-10: Excellent - minimal documented debt
  • 11-30: Good - manageable debt levels
  • 31-100: Moderate - consider dedicating time to address
  • 100+: High - prioritize technical debt reduction

Stale Branches:

  • Branches inactive for 30+ days may be abandoned
  • Consider cleaning up or merging forgotten branches
  • Review with team before deletion

Large Files:

  • Git-tracked files over 1MB may benefit from:
    • Code splitting or modularization
    • Moving data to separate files or Git LFS
    • Compression or optimization
    • Being added to .gitignore if they're generated/built files

Commit Activity:

  • Low activity may indicate stagnant project
  • Very high activity may indicate need for better planning
  • Consistent activity suggests healthy development pace

Arguments:

  • None

Name

git:fix-cherrypick-robot-pr

Synopsis

/git:fix-cherrypick-robot-pr <pr-url> [error-messages]

Description

The git:fix-cherrypick-robot-pr command replaces a cherrypick-robot PR with a clean, manually-crafted cherry-pick PR that includes fixes the robot cannot handle.

The cherrypick-robot creates automated PRs but cannot:

  • Fix verification failures (JSON validation, missing annotations)
  • Resolve merge conflicts
  • Add context-specific fixes
  • Handle edge cases requiring human judgment
  • Apply repository-specific cleanup

This command helps you create a replacement PR with all necessary fixes applied.

Implementation

1. Extract Information from the Robot PR

Use gh pr view <pr-url> to extract:

  • Base branch (e.g., release-4.19)
  • PR title (to extract bug ID like OCPBUGS-65944)
  • All commit hashes included in the PR
  • PR number for later closure
  • Current PR checks/CI status

Example:

gh pr view <pr-url> --json baseRefName,title,commits,number,statusCheckRollup

2. Analyze Error Messages

Parse the provided error output to identify:

  • Root causes (JSON validation, missing annotations, conflicts, etc.)
  • Affected files
  • Required fixes
  • Fix strategy

Error sources (in priority order):

  1. User-provided error messages (from command arguments)
  2. File path if provided (e.g., /path/to/ci-errors.log)
  3. CI failure URL if provided
  4. Automatically fetch from PR status checks

3. Discover Git Remotes and Create Branch

# Discover the upstream remote (the main repository)
# Look for a remote that's not owned by the current user
UPSTREAM_REMOTE=$(git remote -v | grep "fetch" | grep -v "$(git config user.name)" | awk '{print $1}' | head -1)

# Discover the fork remote (your fork)
FORK_REMOTE=$(git remote -v | grep "$(git config user.name).*push" | awk '{print $1}' | head -1)

# If not found, fall back to common names
UPSTREAM_REMOTE=${UPSTREAM_REMOTE:-upstream}
FORK_REMOTE=${FORK_REMOTE:-origin}

# Fetch the latest base branch
git fetch $UPSTREAM_REMOTE <base-branch>

# Create new branch following naming convention
git checkout -b cherry-pick-<issue-number>-to-<base-branch> $UPSTREAM_REMOTE/<base-branch>

Example branch name: cherry-pick-12345-to-release-1.0

4. Cherry-Pick Commits

Cherry-pick all commits from the robot PR in order:

# For each commit hash extracted from the robot PR
git cherry-pick <commit-hash>

# OR use the cherry-pick-by-patch command
/git:cherry-pick-by-patch <commit-hash>

Handle any conflicts that arise during cherry-picking.

5. Apply Necessary Fixes Based on Errors

Based on the error analysis from step 2, apply the necessary fixes:

Analyze the errors to determine:

  1. Which files are causing failures
  2. What type of failure (validation, conflict, test, build)
  3. What fix strategy is appropriate for the repository

Common fix strategies:

  • Validation failures: Check if files can be excluded from validation or need correction
  • Generated file mismatches: Run repository update/regeneration scripts (e.g., make update, make generate)
  • Merge conflicts: Resolve conflicts by reviewing both sides and understanding the target branch context
  • Test failures: Update tests to be compatible with the target branch
  • Build failures: Update dependencies or build configuration for the target branch

Apply fixes with clear commits:

# Make necessary changes based on error analysis
# Stage and commit each logical fix separately
git add <affected-files>
git commit -m "<clear description of what was fixed and why>"

Note: The specific fix commands will vary by repository. Consult the repository's documentation for:

  • Verification script locations and options
  • Code generation/update commands
  • Testing conventions
  • Contribution guidelines

6. Push and Create Replacement PR

# Use the discovered fork remote (from step 3)
# If running this step separately, rediscover the fork remote:
FORK_REMOTE=$(git remote -v | grep "$(git config user.name).*push" | awk '{print $1}' | head -1)
FORK_REMOTE=${FORK_REMOTE:-origin}

# Push to your fork
git push -u $FORK_REMOTE cherry-pick-<issue-number>-to-<base-branch>

# Create PR using gh CLI
gh pr create \
  --base <base-branch> \
  --title "[<base-branch>] <BUG-ID>: <Description>" \
  --body "$(cat <<'EOF'
## Summary
Cherry-pick of <original-commits> to <base-branch> with manual fixes.

## Commits
- <commit-1-hash>: <commit-1-message>
- <commit-2-hash>: <commit-2-message>

## Fixes Applied
- <description-of-fix-1>
- <description-of-fix-2>

## References
- Original PR: #<robot-pr-number>
- JIRA: <bug-id>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

7. Close the Old Robot PR

Add a comment to the robot PR explaining the closure:

gh pr comment <robot-pr-number> --body "Closing this PR in favor of #<new-pr-number> which includes the following fixes:
- <specific-fix-1>
- <specific-fix-2>

/close"

The /close command triggers the bot to close the PR.

Return Value

  • Success: New PR URL and confirmation that old PR is closed
  • Failure: Error message with specific issue encountered

Examples

Example 1: With Error Messages Pasted Directly

/git:fix-cherrypick-robot-pr https://github.com/org/repo/pull/12345

Error messages:
[paste CI error output here]

The command will:

  1. Extract PR information (base branch, commits, bug ID)
  2. Analyze the error messages to identify failure types
  3. Cherry-pick commits to a new branch
  4. Guide you through applying appropriate fixes based on repository conventions
  5. Create a new PR with fixes applied
  6. Close the old robot PR with explanation

Example 2: With Error Log File Reference

/git:fix-cherrypick-robot-pr https://github.com/org/repo/pull/12345

Error log file: /path/to/ci-errors.log

The command reads the error log file and processes it the same way as Example 1.

Example 3: With CI Failure Page Link

/git:fix-cherrypick-robot-pr https://github.com/org/repo/pull/12345

CI failure: https://ci-system.example.com/logs/...

The command fetches the CI logs from the provided URL and analyzes them.

Example 4: No Error Messages (Auto-detect)

/git:fix-cherrypick-robot-pr https://github.com/org/repo/pull/12345

If no error messages are provided, the command will:

  1. Check PR status using gh pr view
  2. Identify failing checks
  3. Fetch CI logs automatically
  4. Analyze and fix based on detected issues

Arguments

  • $1 (required): PR URL - The URL of the cherrypick-robot PR to fix (e.g., https://github.com/org/repo/pull/12345)
  • $2 (optional): Error messages - Can be:
    • Error messages pasted directly
    • File path to error log (e.g., /path/to/ci-errors.log)
    • CI failure page URL
    • Omitted (will auto-detect from PR status)

Common Issues This Handles

Beyond what the robot can do:

  • ✅ Validation errors - Apply exclusions or corrections based on repository conventions
  • ✅ Generated file mismatches - Run appropriate update/regeneration commands
  • ✅ Merge conflicts - Resolve using context
  • ✅ Test failures - Update tests for target branch compatibility
  • ✅ Build failures - Update dependencies or configuration
  • ✅ Context-specific fixes - Apply fixes appropriate for the target branch
  • ✅ Edge cases - Handle with human judgment

Notes

  • Works with cherrypick-robot PRs across different repositories
  • Error messages help determine exactly what to fix
  • Automatically discovers git remote names (no hardcoded assumptions)
  • All changes pushed to your fork (auto-discovered remote)
  • New PRs target the upstream repository
  • Branch naming convention: cherry-pick-<issue>-to-<release>
  • Maintains full control to add any fixes needed
  • If no error messages provided, will check PR status and CI logs automatically
  • Remote discovery uses git remote -v and git config user.name to identify fork vs upstream
  • Falls back to common names (origin for fork, upstream for main repo) if auto-discovery fails
  • Fix strategies will vary by repository - consult repository documentation for specific commands

Name

git:redescribe

Synopsis

/git:redescribe              # Redescribe the PR for the current branch
/git:redescribe <pr-url>     # Redescribe a specific PR by URL

Description

The /git:redescribe command analyzes a Pull Request's actual code changes (diffs) and commit messages to generate an accurate, up-to-date PR description. It compares the existing description with the reality of the code, proposes a corrected description, and offers to update the PR.

This is particularly useful when:

  • A PR has evolved significantly since it was opened.
  • The initial description was placeholder text.
  • Commits have been squashed or rebased, changing the PR's scope.

The command ensures the description accurately reflects:

  • The problem being solved (from commit messages/Jira context).
  • The changes made (from code diffs).
  • The implementation details.

Implementation

1. Identify Target PR

Determine which PR to operate on:

  • If <pr-url> is provided: Use that PR.
  • If no argument:
    • Context Discovery: Run git remote -v to identify the repository (prefer upstream, then origin).
    • Run gh pr view --repo <owner>/<repo> --json url to find the PR associated with the current branch. This proactively avoids "No default remote" errors.
    • If no PR is found, error out and ask the user to provide a URL or push the branch/open a PR.

2. Gather Context

Collect necessary information using the GitHub CLI (gh) and git:

  1. Fetch PR Details:

    gh pr view <pr-url> --json title,body,baseRefName,headRefName,number
    
    • title: For context (often contains Jira ID).
    • body: The current description (to see what needs changing).
    • headRefName: The source branch.
  2. Fetch Commits:

    gh pr view <pr-url> --json commits
    # OR if local:
    git log <base>..<head>
    
    • Extract commit messages to understand the intent and history.
  3. Fetch Code Diffs:

    gh pr diff <pr-url>
    
    • Analyze the actual code changes.
    • Note: If the diff is very large, prioritize file names, structural changes, and distinct code blocks to avoid context window limits.

3. Generate New Description

Synthesize a new description based on the gathered context.

Analysis Steps:

  1. intent vs. Reality: Compare the commit messages (intent) with the gh pr diff output (reality).
  2. Missing Info: Identify features or fixes in the code that are NOT in the current body.
  3. Obsolete Info: Identify things in the body that are no longer in the code.

Drafting the Description: Create a new Markdown description that includes:

  • Summary: A high-level overview of the change.
  • Motivation: Why is this change needed? (Infer from Jira ID in title or "Fixes" in commits).
  • Changes: A bulleted list of technical changes (e.g., "Added FooComponent", "Refactored bar logic", "Updated dependencies").
  • Testing: A section suggesting how the changes verify the fix (inferred from test files changed).

Style Note: Use standard OpenShift/Kubernetes PR style if typical for the repo (e.g., linking issues, clear headers).

4. Present and Apply

  1. Show the Proposal: Display the New Proposed Description clearly to the user. Optionally show a "Diff" between the old description and the new one if helpful.

  2. Interactive Confirmation: Ask the user:

    "Do you want to update the PR description with these changes? (y/n)"

    • If 'y': Run:

      gh pr edit <pr-url> --body "<new-description>"
      

      Output: "✅ PR Description updated successfully."

    • If 'n': Output: "Action cancelled. Description not updated."

Return Value

  • Success: Confirmation message that PR was updated (or skipped by user choice).
  • Failure: Error message if PR not found, gh CLI fails, or network error.

Examples

Example 1: Redescribe current branch's PR

/git:redescribe

Output:

Found PR #123: "Fix logic error" ... Proposed Description: ... Update PR description? (y/n)

Example 2: Redescribe specific PR

/git:redescribe https://github.com/openshift/console/pull/9999

Arguments

  • [pr-url] (optional): The full URL of the Pull Request to analyze. If omitted, attempts to use the PR for the current checked-out branch.

Name

git:suggest-reviewers

Synopsis

/git:suggest-reviewers [base-branch]

Description

The git:suggest-reviewers command analyzes changed files and suggests the most appropriate reviewers for a pull request. It works with both committed changes on feature branches and uncommitted changes (even on the main branch), making it useful before you've created a branch or made any commits. It prioritizes developers who have actually contributed to the code being modified, using git blame data as the primary signal and OWNERS files as supporting information.

The command performs the following analysis:

  • Identifies all files changed (both committed and uncommitted changes)
  • Runs git blame on changed lines to find recent and frequent contributors
  • Searches for OWNERS files in the directories of changed files (and parent directories)
  • Aggregates and ranks potential reviewers based on:
    • Frequency and recency of contributions to modified code (highest priority)
    • Presence in OWNERS files (secondary consideration)
  • Outputs a prioritized list of suggested reviewers

This command is particularly useful for large codebases with distributed ownership where choosing the right reviewer can be challenging. You can use it at any stage of development - from uncommitted local changes to a complete feature branch ready for PR.

Implementation

Step 1: Determine the base branch

  • If base-branch argument is provided, use it
  • Otherwise, detect the main branch (usually main or master)
  • Verify the base branch exists
# Detect main branch if not provided
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'

Step 2: Get changed files

  • Determine the current branch name
  • Detect if we're on the base branch (main/master) or a feature branch
  • Detect if there are uncommitted changes (staged or unstaged)
  • List all modified, added, or renamed files based on the scenario
  • Exclude deleted files (no one to blame)

Scenario detection:

# Get current branch
current_branch=$(git branch --show-current)

# Check if on base branch
if [ "$current_branch" = "$base_branch" ]; then
  on_base_branch=true
else
  on_base_branch=false
fi

# Check for uncommitted changes
has_uncommitted=$(git status --short | grep -v '^??' | wc -l)

Case 1: On base branch (main/master) with uncommitted changes

# Get staged changes
git diff --name-only --diff-filter=d --cached

# Get unstaged changes
git diff --name-only --diff-filter=d

# Combine and deduplicate

Case 2: On feature branch with only committed changes

# Get all changes from base branch to HEAD
git diff --name-only --diff-filter=d ${base_branch}...HEAD

Case 3: On feature branch with committed + uncommitted changes

# Get committed changes
git diff --name-only --diff-filter=d ${base_branch}...HEAD

# Get uncommitted changes
git diff --name-only --diff-filter=d HEAD
git diff --name-only --diff-filter=d --cached

# Combine and deduplicate all files

Case 4: On base branch with no changes

  • Display error: "No changes detected. Please make some changes or switch to a feature branch."

Step 3: Analyze git blame for changed lines

IMPORTANT: Use the helper script ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py to perform this analysis. Do NOT implement this logic manually.

The script automatically handles:

  • Parsing git diff to identify specific line ranges that were modified
  • Running git blame on those line ranges (not entire files)
  • Extracting and aggregating author information
  • Filtering out bot accounts

For uncommitted changes:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py \
  --mode uncommitted \
  --file <file1> \
  --file <file2> \
  --output json

For committed changes on feature branch:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/suggest-reviewers/analyze_blame.py \
  --mode committed \
  --base-branch ${base_branch} \
  --file <file1> \
  --file <file2> \
  --output json

Output format:

{
  "Author Name": {
    "line_count": 45,
    "most_recent_date": "2024-10-15T14:23:10",
    "files": ["file1.go", "file2.go"],
    "email": "author@example.com"
  }
}

Step 4: Find OWNERS files

  • For each changed file, search for OWNERS files in:
    • The same directory
    • Parent directories up to repository root
  • Parse OWNERS files to extract:
    • approvers: People who can approve changes
    • reviewers: People who can review changes
  • OWNERS file format (YAML):
    approvers:
      - username1
      - username2
    reviewers:
      - username3
      - username4
    

Step 5: Aggregate and rank reviewers

  • Combine data from git blame and OWNERS files
  • Rank potential reviewers based on weighted scoring:
    1. Lines contributed (weight: 10) - More lines modified = better knowledge
    2. Recency (weight: 5) - Recent contributions = current knowledge
    3. OWNERS approver + contributor (weight: 3 bonus) - Authority + knowledge
    4. OWNERS reviewer + contributor (weight: 2 bonus) - Review rights + knowledge
    5. OWNERS only, no contributions (weight: 1) - Authority but may lack specific knowledge
  • Exclude the current PR author from suggestions
  • Filter out bot accounts (e.g., "openshift-bot", "k8s-ci-robot", "*[bot]")
  • Normalize scores and sort by total score

Step 6: Output results

  • Display reviewers in ranked order
  • Show why each reviewer is suggested (contribution count, recency, OWNERS role)
  • Group by priority tiers based on score ranges
  • Include GitHub usernames if available
  • Show files each reviewer has worked on

Return Value

  • Claude agent text: Formatted list of suggested reviewers including:
    • Primary reviewers: Major contributors to the modified code
    • Secondary reviewers: Moderate contributors or OWNERS with some contributions
    • Additional reviewers: OWNERS members or minor contributors
    • Explanation for each suggestion (e.g., "Modified 45 lines across 3 files, last contribution 5 days ago, OWNERS approver")
    • Summary of analysis (files analyzed, OWNERS files found, total lines changed)

Examples

  1. Basic usage (auto-detect base branch):

    /git:suggest-reviewers
    

    Output:

    Analyzed 8 files changed from main (245 lines modified)
    Found 3 OWNERS files
    
    PRIMARY REVIEWERS:
    - @alice (modified 89 lines across 4 files, last contribution 5 days ago, OWNERS approver)
    - @bob (modified 67 lines in pkg/controller/manager.go, last contribution 2 weeks ago)
    
    SECONDARY REVIEWERS:
    - @charlie (modified 45 lines across 2 files, last contribution 1 month ago, OWNERS reviewer)
    - @diana (modified 23 lines in pkg/api/handler.go, last contribution 3 weeks ago)
    
    ADDITIONAL REVIEWERS:
    - @eve (OWNERS approver in pkg/util/, no recent contributions to changed code)
    
    Recommendation: Add @alice and @bob as reviewers
    
  2. Specify base branch:

    /git:suggest-reviewers release-4.15
    

    Output:

    Analyzed 3 files changed from release-4.15 (78 lines modified)
    Found 2 OWNERS files
    
    PRIMARY REVIEWERS:
    - @frank (modified 56 lines in vendor/kubernetes/client.go, last contribution 1 week ago, OWNERS approver)
    
    SECONDARY REVIEWERS:
    - @grace (modified 12 lines in vendor/kubernetes/types.go, last contribution 2 months ago)
    - @henry (OWNERS reviewer in vendor/kubernetes/, contributed to adjacent code 1 month ago)
    
    Recommendation: Add @frank as primary reviewer, @grace as optional
    
  3. No OWNERS files found:

    /git:suggest-reviewers
    

    Output:

    Analyzed 5 files changed from main (156 lines modified)
    No OWNERS files found in modified paths
    
    SUGGESTED REVIEWERS (based on code contributions):
    - @isabel (modified 89 lines across 4 files, last contribution 5 days ago)
    - @jack (modified 34 lines in src/main.ts, last contribution 10 days ago)
    - @karen (modified 12 lines in src/utils.ts, last contribution 3 months ago)
    
    Note: No OWNERS files found. Consider consulting team leads for additional reviewers.
    
  4. Single file change:

    /git:suggest-reviewers
    

    Output:

    Analyzed 1 file changed from main: src/auth/login.ts (34 lines modified)
    Found 1 OWNERS file
    
    PRIMARY REVIEWERS:
    - @lisa (modified 28 lines, last contribution 3 weeks ago, OWNERS approver)
    
    SECONDARY REVIEWERS:
    - @mike (modified 6 lines, last contribution 2 months ago, OWNERS reviewer)
    
    Recommendation: Add @lisa as reviewer
    
  5. OWNERS members with no contributions:

    /git:suggest-reviewers
    

    Output:

    Analyzed 4 files changed from main (112 lines modified)
    Found 2 OWNERS files
    
    PRIMARY REVIEWERS:
    - @noah (modified 78 lines across 3 files, last contribution 1 week ago)
    
    SECONDARY REVIEWERS:
    - @olivia (modified 34 lines in pkg/config/parser.go, last contribution 5 weeks ago)
    
    ADDITIONAL REVIEWERS:
    - @paul (OWNERS approver in pkg/, no contributions to changed code)
    - @quinn (OWNERS reviewer in pkg/, no contributions to changed code)
    
    Recommendation: Add @noah as primary reviewer. OWNERS members @paul and @quinn
    may provide approval but consider @noah for technical review.
    
  6. Uncommitted changes on main branch:

    /git:suggest-reviewers
    

    Output:

    Analyzing uncommitted changes on main branch
    Found 3 modified files (2 staged, 1 unstaged) - 87 lines modified
    Found 1 OWNERS file
    
    PRIMARY REVIEWERS:
    - @rachel (modified 45 lines across 2 files, last contribution 2 weeks ago, OWNERS approver)
    - @steve (modified 32 lines in src/api/handler.ts, last contribution 1 month ago)
    
    SECONDARY REVIEWERS:
    - @tina (modified 10 lines in src/utils/format.ts, last contribution 3 months ago)
    
    Recommendation: Add @rachel and @steve as reviewers
    
    Note: These are uncommitted changes. Consider creating a feature branch and committing before creating a PR.
    
  7. Uncommitted changes on feature branch:

    /git:suggest-reviewers
    

    Output:

    Analyzing branch feature/add-logging (includes uncommitted changes)
    - Committed changes from main: 4 files, 156 lines
    - Uncommitted changes: 2 files, 34 lines
    Total: 5 unique files, 190 lines modified
    Found 2 OWNERS files
    
    PRIMARY REVIEWERS:
    - @uma (modified 98 lines across 3 files, last contribution 1 week ago, OWNERS reviewer)
    - @victor (modified 67 lines in pkg/logger/logger.go, last contribution 2 weeks ago)
    
    SECONDARY REVIEWERS:
    - @wendy (modified 25 lines in pkg/config/settings.go, last contribution 1 month ago, OWNERS approver)
    
    Recommendation: Add @uma and @victor as reviewers
    
    Note: You have uncommitted changes. Consider committing them before creating a PR.
    
  8. No changes detected:

    /git:suggest-reviewers
    

    Output:

    Error: No changes detected.
    
    You are on branch 'main' with no uncommitted changes.
    
    To use this command:
    - Make some changes to files (staged or unstaged), or
    - Switch to a feature branch with committed changes, or
    - Create a new feature branch with: git checkout -b feature/your-feature-name
    

Arguments

  • base-branch (optional): The base branch to compare against (default: auto-detect main branch, usually main or master)

Notes

  • The command analyzes both committed and uncommitted changes
  • Works on any branch, including main/master (analyzes uncommitted changes in this case)
  • For uncommitted changes, git blame is run on HEAD; for committed changes, on the base branch
  • OWNERS files must be in YAML format with approvers and/or reviewers fields
  • The current user (detected from git config) is automatically excluded from suggestions
  • Reviewers are ranked primarily by their contribution to the specific code being changed
  • OWNERS membership provides a bonus but is not the primary ranking factor
  • If no reviewers are found via git blame, OWNERS members will be suggested as fallback
  • If you're on the base branch with no uncommitted changes, the command will display an error

Name

git:summary

Synopsis

/git:summary

Description

The git:summary command provides a comprehensive overview of the current Git repository state. It displays the current branch, tracking status, working tree status, and recent commit history in a single concise view. This command is designed to give developers quick context about their repository without running multiple Git commands manually.

It provides essential information for developers including:

  • Current branch and remote tracking status (ahead/behind)
  • Working tree status (modified, staged, and untracked files)
  • Recent commit history with one-line summaries
  • Uncommitted changes summary

The spec sections is inspired by https://man7.org/linux/man-pages/man7/man-pages.7.html#top_of_page

Implementation

  • Executes multiple git commands to gather repository state
  • Retrieves current branch name and tracking information
  • Shows git status for modified, staged, and untracked files
  • Displays last 5 commits with one-line summaries
  • Summarizes uncommitted changes
  • Formats output for clear readability
  • All information is read-only with no side effects

Implementation logic:

# Get current branch and tracking status
git branch -vv

# Show working tree status
git status --short

# Display recent commits
git log --oneline -5

# Summarize uncommitted changes
git diff --stat

Return Value

  • Claude agent text: Formatted summary including:
    • Current branch name and remote tracking status
    • List of modified, staged, and untracked files
    • Last 5 commit messages with hashes
    • Statistics of uncommitted changes

Examples

  1. Basic usage:

    /git:summary
    

    Output:

    Current branch: main
    Your branch is up to date with 'origin/main'.
    
    Modified files:
     M src/index.ts
    ?? temp/
    
    Recent commits:
    abc123 Fix authentication bug
    def456 Add user profile feature
    ghi789 Update dependencies
    jkl012 Refactor database layer
    mno345 Initial commit
    
    Uncommitted changes:
    1 file changed, 15 insertions(+), 3 deletions(-)
    
  2. Repository with no changes:

    /git:summary
    

    Output:

    Current branch: develop
    Your branch is up to date with 'origin/develop'.
    
    Working tree clean
    
    Recent commits:
    pqr678 Merge pull request #42
    stu901 Add test coverage
    vwx234 Fix linting issues
    yza567 Update README
    bcd890 Release v2.0.0
    

Arguments:

  • None

Sponsors

Details

Marketplace
openshift-eng/ai-helpers
Source
plugins/git
Category
Tooling
Keywords
git, workflow, automation

More from openshift-eng/ai-helpers

All 56