| name | git |
| description | Usage for basic Git operations and repository management. This is the core skill for all git interactions. You MUST load this skill when using git command-line. |
| license | MIT |
Git
Expert in advanced git usage for repository agents. Prioritize non-interactive, safe, reproducible operations that
maintain clean history and respect repository conventions.
WHEN TO USE
- A user wants to understand repository git hooks related to their commits.
- The agent needs to perform safe, non-interactive Git lifecycle tasks.
- User asks for help to execute Git operations natively (committing, moving files, merging).
- User encounters issues when amending or reverting code changes in history.
WHEN NOT TO USE
- When managing massive binary blobs where Git LFS or external artifact storage is required.
- For interacting with GitHub-specific abstractions like Pull Requests, Issues, or GitHub Actions (use
gh instead).
- When resolving excessively complex merge conflicts that require human intuition and domain knowledge to untangle correctly.
Core Principles
- Anti-Panic Mutation Ban (Desperation Guardrail): NEVER chain rapid-fire state-mutating Git commands
(e.g., force-pushes, recursive
git commit --amend, or git reset --hard) as a blind fallback when a prior
command fails.
If an operation fails unexpectedly, you MUST immediately halt state-mutation and execute purely
read-only diagnostic commands (git status, git log) to re-sync your mental model.
- Atomic changes: Favor small, focused commits. Use amend/fixup patterns for corrections.
- Conventional Commits: Always use the format
<type>[optional scope]: <description> with a blank line and detailed
body if needed.
- Hook handling: Aim to satisfy pre-commit/pre-push hooks. Use
--no-verify only as a last resort when hooks are
non-critical or environment-specific.
- Linear history: Prefer rebase over merge for feature branches to keep history clean and bisectable.
- Non-interactive execution: Commands must run without prompting. Never use interactive modes (
-i, --interactive,
default editors).
- Safety: Never perform destructive operations without explicit reasoning and user confirmation.
- Situational Awareness & OODA (Observe, Orient, Decide, Act) Loop Enforcer: Before executing Git operations with
side-effects (e.g.
git add, git commit, git rm), always verify your environmental context (e.g., checking
git status or pwd to ensure you aren't inadvertently crossing submodule boundaries).
Observe and Orient using read-only commands to establish ground-truth before you Decide and Act.
Non-Interactive Patterns
- Amending last commit (preserve author date):
git commit --amend --no-edit --date="$(git log -1 --format=%aD)"
- Renaming files (preserve history):
git mv old_file new_file (instead of mv or rm)
- Fixup previous commits (non-interactive preparation):
- Create fixup:
git commit --fixup <commit-sha>
- Later autosquash (requires interactive rebase - propose to user or defer to PR squash if agent cannot handle
-i):
git rebase -i --autosquash origin/main
- Rebasing feature branches:
git fetch origin && git rebase origin/main --no-verify (add --no-verify only if
hooks block)
- Cherry-picking without conflicts:
git cherry-pick -x <commit-sha> (-x records original SHA for traceability)
- Cherry-picking with editor bypass:
GIT_EDITOR=true git cherry-pick --continue (auto-accept commit message during
conflict resolution)
- Stashing partial work (non-interactive):
git stash push -m "wip-description" -- path/to/file (use pathspec for
selective stashing; avoid -p as it is interactive)
Bypassing Editor Prompts
Git commands that normally open an editor can be made non-interactive:
- Set editor to true:
GIT_EDITOR=true git <command> (auto-accepts default message)
- Use --no-edit flag:
git commit --amend --no-edit, git merge --no-edit, git revert --no-edit
- Pre-set commit message:
git commit -m "message" (avoids editor entirely)
- Cherry-pick continuation:
GIT_EDITOR=true git cherry-pick --continue (after resolving conflicts)
- Revert with message:
git revert <commit-sha> --no-edit (uses default revert message)
Important: Automation tools (like report_progress) may fail if they encounter editor prompts.
Always use non-interactive patterns when preparing changes for automated tools.
Working with Shallow Clones
GitHub Actions and other CI environments often check out repositories as shallow clones (limited history).
Note: This repository is configured to check out as unshallow by default (fetch-depth: 0) in its main workflows.
- Detect shallow clone:
test -f .git/shallow && echo "Shallow clone" || echo "Full clone"git rev-parse --is-shallow-repository (outputs true or false)
- Unshallow repository:
git fetch --unshallow origin <current-branch>
(retrieves complete history for the current branch).
Then fetch target branches if needed (e.g., git fetch origin <target-branch>).
Avoid using just git fetch --unshallow as it may fail or be incomplete in CI environments.
- Find commits not in current branch:
- Check if commit exists:
git cat-file -e <commit-sha> 2>/dev/null && echo "Exists" || echo "Not found"
- Search across all branches:
git log --all --oneline | grep <commit-sha-prefix>
- Fetch specific PR:
git fetch origin pull/<pr-number>/head:pr-<pr-number>
- List all branches containing commit:
git branch -a --contains <commit-sha>
Safety & Recovery
- Check repository state non-interactively:
- Clean working tree:
git diff --quiet && git diff --cached --quiet
- Current branch:
git rev-parse --abbrev-ref HEAD
- Unpushed commits:
git log origin/$(git rev-parse --abbrev-ref HEAD)..HEAD
- Reflog for recovery: Reference
git reflog before history-rewriting operations to enable rollback.
- Backup before destructive ops: Create temp tag:
git tag backup/pre-op-$(date +%s)
- Force push only when required (e.g., after approved history rewrite):
git push --force-with-lease origin <branch>
- Conflict Marker Prevention: Before running
git commit, verify that there are no unresolved merge conflict markers. Use git diff --cached to ensure no markers (e.g., <<<<<<<, =======, >>>>>>>) are being committed. NEVER commit a file containing unresolved merge conflicts.
- Reverting Commits:
- For simple reverts, use
git revert <commit-sha> --no-edit.
- If a revert results in conflicts, it will pause. DO NOT blindly commit. You MUST resolve the conflicts in the files, ensuring all
<<<<<<<, =======, and >>>>>>> markers are removed.
- Once resolved, stage the files and use
GIT_EDITOR=true git revert --continue.
Useful Diagnostic Commands
- Commit template check:
git config commit.template
- Generate Mermaid
gitGraph commit lines:
- With Git (
git):
git log origin/main..HEAD --reverse --format='commit id: "%s"'
(Note: if commit subjects contain " characters, escape them so Mermaid string parsing stays valid—see the
GitGraph guidance in mermaid/SKILL.md.)
- With GitHub API (
gh api):
gh api repos/<owner>/<repo>/pulls/<number>/commits --jq '.[] | "commit id: \"[\(.sha[0:7])] \(.commit.message | split("\n")[0] | gsub("\""; "'\''"))\""'
- With GitHub CLI (
gh):
gh pr view <number> --json headRefName,baseRefName,commits
- For more context, load relevant skill files when working with this type of diagrams.
- Inspect branch graph for last commits (useful when finding and identifying failing/problematic commit):
git --no-pager log --oneline --decorate --graph --all --max-count=20 --simplify-by-decoration
- Remote tracking status:
git status -sb
- Signed commit verification:
git log --show-signature -1
- Verify identity:
git config user.name && git config user.email
- View commits on a branch:
git log --oneline origin/main..origin/feature/branch (alternative to gh pr view)
Resolving Merge Conflicts with Minimal Changes
When a merge introduces too many unrelated changes, maintain PR focus with selective conflict resolution:
- Reset to clean state:
git reset --hard <commit-sha> (reset to commit before problematic merge)
- Revert merge commit:
git revert -m 1 <merge-commit-sha> --no-edit (revert merge keeping first parent)
- Remove lock files:
rm .git/index.lock (if git operations fail due to lock)
- Check file state in commit:
git ls-tree -r <commit-sha>:.github/workflows/ --name-only (list files at specific
commit)
- Verify changes:
git diff <commit-sha> HEAD --name-status (compare commits to see what changed)
Strategy for focused PRs:
- Avoid merging large changesets when PR has single purpose
- Use
git reset --hard to target commit with desired changes only
- Document resolution approach for future reference
- Keep PR changes minimal and reviewable
Integrating Changes from Target Branch (Avoiding Merge Commits)
Problem: When asked to "integrate changes from dev/main", using git merge <target-branch> creates a merge commit
that includes ALL commits from the target branch in your PR, making it impossible to review only your feature changes.
Solution: Rebase your commits on top of the target branch using the cherry-pick workflow.
Step-by-Step Cherry-Pick Workflow
-
Identify your feature commits:
git log --oneline origin/<target-branch>..HEAD
git log --oneline origin/<target-branch>..HEAD | awk '{print $1}' | tac
-
Fetch latest target branch:
git fetch origin <target-branch>
-
Create backup before destructive operation:
git tag backup/before-rebase-$(date +%s)
-
Reset branch to target (creates clean starting point):
git reset --hard origin/<target-branch>
-
Cherry-pick your feature commits:
git cherry-pick <commit-1> <commit-2> <commit-3>
git cherry-pick <first-commit>^..<last-commit>
-
Handle conflicts during cherry-pick:
- Resolve conflicts in files (preserve target content, add your changes)
- Stage resolved files:
git add <resolved-files>
- Continue non-interactively:
GIT_EDITOR=true git cherry-pick --continue
- Or skip commit:
git cherry-pick --skip
- Or abort:
git cherry-pick --abort
-
Verify only your changes are present:
git diff origin/<target-branch>..HEAD --name-status
git diff origin/<target-branch>..HEAD --stat
git log --oneline origin/<target-branch>..HEAD | wc -l
The diff should show ONLY files you created/modified for your feature, not unrelated files from target branch.
Common Pitfalls
- Merge commits in PR: Indicates wrong approach was used. Start over with reset + cherry-pick workflow.
- Too many changed files: Verify you reset to correct target branch before cherry-picking.
- Conflict resolution mistakes: When resolving conflicts, don't remove existing target branch content - only add your feature changes.
- Wrong commit order: When cherry-picking multiple commits, maintain original chronological order.
- Committing Conflict Markers: Blindly committing files that still contain
<<<<<<<, =======, and >>>>>>>.
Working with Automation Tools
CRITICAL: Automation tools like report_progress automatically attempt to rebase your branch against the
remote tracking branch. This causes session crashes when:
- You've rewritten history (e.g., using reset + cherry-pick)
- Your branch has diverged from remote
- The remote has many commits that would trigger rebase conflicts
The crash sequence:
- Tool switches to your branch
- Tool runs
git rebase origin/<your-branch> automatically
- Rebase encounters conflicts from diverged history
- Tool cannot resolve conflicts interactively -> crash
Prevention Strategies
Strategy 1: Use New Branch Name (Safest after history rewrite)
git checkout -b <feature>-v2
git checkout -b <feature>-rebased
Strategy 2: Manual Push Before Automation
If you must reuse the same branch:
git fetch origin <target-branch>
git reset --hard origin/<target-branch>
git cherry-pick <commits...>
git diff origin/<target-branch>..HEAD --stat
Strategy 3: Fresh Branch from Clean State
git checkout -b <new-feature-branch> origin/<target-branch>
Detection: When You've Hit This Issue
Error patterns indicating auto-rebase crash:
Rebasing (1/NNN) where NNN is very large (e.g., 113 commits)error: could not apply <commit-sha>...CONFLICT (content): Merge conflict in <file>warning: skipped previously applied commit- Session terminates with
GitError: rebase git error
Recovery Steps
If automation tool fails with rebase errors:
- Abort the rebase:
git rebase --abort
- Verify your local state:
git log --oneline -5 and git diff origin/<target-branch>..HEAD --stat
- Choose recovery path:
- Create new branch:
git checkout -b <branch>-v2 && git push origin <branch>-v2
- Or explain to user: "Branch ready at commit
<sha>, needs manual push: git push --force-with-lease origin <branch>"
Best Practice: Complete all git operations manually (fetch, reset, cherry-pick, verify) BEFORE calling
automation tools. The tool will then simply push your clean, prepared commits.
Example: Rebasing Feature Branch on Dev
git log --oneline origin/dev..HEAD
git fetch origin dev
git tag backup/before-dev-$(date +%s)
git reset --hard origin/dev
git cherry-pick ghi789 def456 abc123
git log --oneline origin/dev..HEAD
git diff origin/dev..HEAD --stat
Troubleshooting tips
- Always use non-interactive git commands (e.g., git commit -m) to prevent editor locks in
automation.
- Never trust only success messages - verify branches exist on the remote using git ls-remote or
the GitHub UI after any push.
- For rewritten or rebased branches, use git push -f or push to a new branch; never attempt a
normal push.
- Check for merge conflicts (git status) before any push, and abort (git rebase --abort) and
clean up on conflict.
- Handling rejected pushes (fetch first): If
git push fails with rejected ... (fetch first)
because the remote contains new work you do not have locally, NEVER forcefully overwrite it.
In non-GitHub-Actions environments, pull the latest changes first
(e.g. git pull --rebase origin <branch>) to apply your local commits on top of the remote changes,
resolve conflicts if any, and then retry git push.
In GitHub Actions runtime, use git pull --no-rebase origin <branch> (merge semantics) instead,
as the workflow's auto-PR/push logic requires compatible remote branch history.
- Inspect all push/rebase failures in logs - manual intervention may be required if you see
non-fast-forward or remote rejection errors.
- Use unique branch names if retrying after failure or history rewrite.
- Ensure your automation accounts have the correct GitHub permissions to create and push
branches.
What to Avoid
- Interactive operations (
git rebase -i, git add -p without scripting, editor prompts).
- Direct pushes to protected branches (main/master).
git pull in scripts - prefer explicit fetch + rebase or merge --no-edit.--force pushes without --force-with-lease.- Unqualified
git reset --hard (prefer git reset --hard origin/main with backup tag).
- When user asks to remove files, use
git rm instead of rm.
Always explain proposed git operations step-by-step, quote exact commands, and confirm irreversible actions with the
user.
References
To fully utilize this skill, you MUST read at least one of the links relevant to the current context:
- Git Filter Branch
Reference MUST be loaded before running
git filter-branch for history rewriting and subdirectory extraction tasks.
- Bisecting (git bisect)
Reference MUST be loaded before running
git bisect to track down regressions or bugs.
- Advanced Cherry-Picking (git cherry-pick)
Reference MUST be loaded when performing advanced cherry-picking operations across branches.
- Git Merge
Reference MUST be loaded before performing a git merge, ensuring no conflict markers or duplicate lines are present.
- Git Rebase
Reference MUST be loaded before performing Git rebase operations (interactive history cleanup or non-interactive rewrites).
- Git Submodule Management
Reference MUST be loaded when managing, adding, or removing Git submodules safely.
- Reflog Recovery (git reflog)
Reference MUST be loaded when using
git reflog to recover lost commits, branches, or undo destructive operations.
- Git Recovery & Troubleshooting
Reference MUST be loaded when performing repository recovery, solving complex conflicts, or manipulating history.
