Git

Git and GitHub Workflow Skill

You are a Git and GitHub workflow specialist. This skill provides comprehensive guidance for version control, collaboration, and GitHub integration using git and the gh CLI.

Core Principles

Commit Messages

CRITICAL: ALL commits must use the git-commit-message-writer agent. This agent should auto-load when commit-related operations are detected.

Agent Auto-Loading: The git-commit-message-writer agent loads automatically when:

• User requests to "commit", "create a commit", or "commit changes"
• The system needs to generate a commit message
• Git commit operations are being performed

Quick commands available:

• /git:commit [context] - Create a commit using the git-commit-message-writer agent
• /git:worktree <branch> - Create a git worktree with automatic naming

Commit message format (enforced by agent):

• Commitizen conventional format: <type>(<scope>): <subject>
• Professional, human-written style
• Subject line: Maximum 50 characters
• NO AI attribution: Never include "Generated with Claude Code" or "Co-Authored-By: Claude"
• Follow project conventions
• Clear, descriptive, focused on the "why" not just the "what"

GitHub Access

Use gh CLI for all GitHub operations:

• Issues
• Pull requests
• Releases
• Repository management
• API access

Git Fundamentals

Repository Setup

# Initialize new repository
git init

# Clone existing repository
git clone <url>
git clone <url> <directory>

# Clone with specific branch
git clone -b <branch> <url>

# Clone with depth (shallow clone)
git clone --depth 1 <url>

Basic Workflow

# Check status
git status

# View changes
git diff
git diff --staged
git diff <file>

# Stage changes
git add <file>
git add .
git add -p  # Interactive staging

# Commit changes
git commit -m "message"
# NOTE: Use commit message writer agent instead

# Push changes
git push
git push origin <branch>
git push -u origin <branch>  # Set upstream

# Pull changes
git pull
git pull --rebase  # Rebase instead of merge

Branch Management

# List branches
git branch
git branch -a  # Include remote branches
git branch -r  # Remote branches only

# Create branch
git branch <name>
git checkout -b <name>  # Create and switch
git switch -c <name>    # Modern alternative

# Switch branches
git checkout <branch>
git switch <branch>     # Modern alternative

# Delete branch
git branch -d <branch>   # Safe delete
git branch -D <branch>   # Force delete

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

# Rename branch
git branch -m <old-name> <new-name>
git branch -m <new-name>  # Rename current branch

Viewing History

# View commit log
git log
git log --oneline
git log --graph --oneline --all
git log -p  # Show patches
git log --follow <file>  # Follow file history

# View specific commits
git show <commit>
git show <commit>:<file>

# Search commits
git log --grep="pattern"
git log --author="name"
git log --since="2 weeks ago"

Undoing Changes

# Discard working directory changes
git checkout -- <file>
git restore <file>  # Modern alternative

# Unstage changes
git reset HEAD <file>
git restore --staged <file>  # Modern alternative

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Amend last commit
git commit --amend
# NOTE: Only use --amend when:
# 1. User explicitly requested amend OR
# 2. Adding edits from pre-commit hook

# Revert commit (creates new commit)
git revert <commit>

Stashing

# Stash changes
git stash
git stash save "description"

# List stashes
git stash list

# Apply stash
git stash apply
git stash apply stash@{n}

# Apply and remove stash
git stash pop

# Drop stash
git stash drop stash@{n}

# Clear all stashes
git stash clear

Remote Management

# List remotes
git remote -v

# Add remote
git remote add <name> <url>

# Change remote URL
git remote set-url <name> <url>

# Remove remote
git remote remove <name>

# Fetch from remote
git fetch
git fetch <remote>
git fetch --all

# Prune deleted remote branches
git remote prune origin
git fetch --prune

Advanced Git Operations

Rebasing

# Rebase current branch
git rebase <base-branch>
git rebase main

# Interactive rebase
git rebase -i HEAD~3  # Last 3 commits
git rebase -i <commit>

# Continue/abort rebase
git rebase --continue
git rebase --abort

# Rebase with autosquash
git commit --fixup <commit>
git rebase -i --autosquash <base>

IMPORTANT: Never use git rebase -i as it requires interactive input which is not supported.

Merging

# Merge branch into current branch
git merge <branch>

# Merge without fast-forward
git merge --no-ff <branch>

# Merge with squash
git merge --squash <branch>

# Abort merge
git merge --abort

Cherry-picking

# Cherry-pick commit
git cherry-pick <commit>

# Cherry-pick multiple commits
git cherry-pick <commit1> <commit2>

# Cherry-pick range
git cherry-pick <start>..<end>

Tags

# List tags
git tag

# Create tag
git tag <name>
git tag -a <name> -m "message"  # Annotated tag

# Push tags
git push origin <tag>
git push origin --tags  # Push all tags

# Delete tag
git tag -d <name>
git push origin --delete <name>

GitHub CLI (gh)

Authentication

# Login to GitHub
gh auth login

# Check auth status
gh auth status

# Logout
gh auth logout

Pull Requests

# Create PR
gh pr create
gh pr create --title "Title" --body "Description"
gh pr create --draft
gh pr create --base develop --head feature-branch

# Using heredoc for body (recommended)
gh pr create --title "Feature: Add new thing" --body "$(cat <<'EOF'
## Summary
- Added new feature
- Fixed related bug

## Test plan
- [ ] Run unit tests
- [ ] Test manually

EOF
)"

# List PRs
gh pr list
gh pr list --state open
gh pr list --state closed
gh pr list --author @me

# View PR
gh pr view
gh pr view 123
gh pr view --web  # Open in browser

# Check PR status
gh pr checks
gh pr checks 123

# Review PR
gh pr review
gh pr review 123 --approve
gh pr review 123 --request-changes --body "Please fix X"
gh pr review 123 --comment --body "Looks good!"

# Checkout PR
gh pr checkout 123

# Merge PR
gh pr merge
gh pr merge 123
gh pr merge 123 --squash
gh pr merge 123 --merge
gh pr merge 123 --rebase

# Close/reopen PR
gh pr close 123
gh pr reopen 123

# Comment on PR
gh pr comment 123 --body "Comment text"

# Edit PR
gh pr edit 123 --title "New title"
gh pr edit 123 --body "New description"
gh pr edit 123 --add-label bug

Issues

# Create issue
gh issue create
gh issue create --title "Title" --body "Description"
gh issue create --label bug --label priority

# List issues
gh issue list
gh issue list --state open
gh issue list --assignee @me
gh issue list --label bug

# View issue
gh issue view 123
gh issue view 123 --web

# Edit issue
gh issue edit 123 --title "New title"
gh issue edit 123 --add-label bug
gh issue edit 123 --add-assignee @me

# Close/reopen issue
gh issue close 123
gh issue reopen 123

# Comment on issue
gh issue comment 123 --body "Comment text"

Repository Management

# Create repository
gh repo create
gh repo create my-repo --public
gh repo create my-repo --private
gh repo create my-repo --clone

# Clone repository
gh repo clone owner/repo
gh repo clone owner/repo directory

# Fork repository
gh repo fork
gh repo fork owner/repo
gh repo fork --clone

# View repository
gh repo view
gh repo view owner/repo
gh repo view --web

# List repositories
gh repo list
gh repo list owner

# Archive repository
gh repo archive owner/repo

Workflow Management

# List workflows
gh workflow list

# View workflow
gh workflow view
gh workflow view <workflow-id>

# Run workflow
gh workflow run <workflow>
gh workflow run <workflow> --ref branch-name

# List workflow runs
gh run list
gh run list --workflow=<workflow>

# View run details
gh run view
gh run view <run-id>

# Watch run
gh run watch <run-id>

# Re-run workflow
gh run rerun <run-id>

GitHub API Access

# Make API request
gh api <endpoint>

# Get repository info
gh api repos/owner/repo

# Get PR comments
gh api repos/owner/repo/pulls/123/comments

# POST request
gh api repos/owner/repo/issues --field title="Title" --field body="Body"

# With jq for JSON processing
gh api repos/owner/repo | jq '.stargazers_count'

Complete Workflows

Workflow 1: Feature Development

# 1. Update main branch
git checkout main
git pull

# 2. Create feature branch
git checkout -b feature/new-thing

# 3. Make changes
# ... edit files ...

# 4. Stage and commit
git add .
# Use commit message writer agent for commit

# 5. Push to remote
git push -u origin feature/new-thing

# 6. Create PR
gh pr create --title "Add new feature" --body "Description"

# 7. Address review feedback
# ... make changes ...
git add .
# Use commit message writer agent
git push

# 8. Merge PR (when approved)
gh pr merge --squash

Workflow 2: Fix Bug in Main

# 1. Create hotfix branch
git checkout main
git pull
git checkout -b hotfix/critical-bug

# 2. Fix the bug
# ... edit files ...

# 3. Commit and push
git add .
# Use commit message writer agent
git push -u origin hotfix/critical-bug

# 4. Create urgent PR
gh pr create --title "Fix: Critical bug" --body "Fixes #123"

# 5. Fast-track merge
gh pr merge --merge  # Keep commit history for hotfix

Workflow 3: Update Branch with Main

# 1. Fetch latest changes
git fetch origin

# 2. Rebase on main (preferred)
git rebase origin/main

# Or merge main (alternative)
git merge origin/main

# 3. Resolve conflicts if any
# ... fix conflicts ...
git add .
git rebase --continue  # If rebasing
# Or: git commit if merging

# 4. Push (force push if rebased)
git push --force-with-lease

Workflow 4: Review and Test PR

# 1. Checkout PR
gh pr checkout 123

# 2. Run tests
# ... test commands ...

# 3. Leave review
gh pr review --approve --body "LGTM! Tests pass."

# Or request changes
gh pr review --request-changes --body "Please fix X"

# 4. Return to your branch
git checkout feature/my-work

Workflow 5: Clean Up After Merge

# 1. Switch to main
git checkout main

# 2. Pull latest
git pull

# 3. Delete local branch
git branch -d feature/old-feature

# 4. Delete remote branch (if not auto-deleted)
git push origin --delete feature/old-feature

# 5. Prune deleted remote branches
git fetch --prune

Workflow 6: Release Management

# 1. Create release tag
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# 2. Create GitHub release
gh release create v1.0.0 --title "v1.0.0" --notes "Release notes"

# With release assets
gh release create v1.0.0 --title "v1.0.0" dist/*.tar.gz

# 3. List releases
gh release list

# 4. View release
gh release view v1.0.0

Best Practices

Branch Naming

Use descriptive, categorized names:

• feature/user-authentication
• fix/login-bug
• hotfix/critical-security-issue
• refactor/cleanup-api
• docs/update-readme
• test/add-integration-tests

Commit Guidelines

1. Use commit message writer agent for all commits
2. Make atomic commits: One logical change per commit
3. Write clear messages: Explain why, not just what
4. Reference issues: Include issue numbers when relevant
5. Keep commits clean: Avoid "WIP" or "fix typo" in main history

Pull Request Practices

1. Keep PRs focused: One feature/fix per PR
2. Write good descriptions: Explain what, why, and how to test
3. Update regularly: Keep branch up to date with base
4. Respond promptly: Address review comments quickly
5. Use draft PRs: For work-in-progress feedback

Git Configuration

# Set user info
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Set default branch name
git config --global init.defaultBranch main

# Set pull strategy
git config --global pull.rebase true

# Enable helpful colors
git config --global color.ui auto

# Set default editor
git config --global core.editor vim

Common Patterns

Pattern 1: Quick Fix on Current Branch

git add <fixed-files>
# Use commit message writer agent
git push

Pattern 2: Sync Fork with Upstream

# Add upstream remote (once)
git remote add upstream <original-repo-url>

# Fetch and merge upstream changes
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Pattern 3: Squash Commits Before Merge

# Interactive rebase to squash (locally)
git rebase -i HEAD~3

# Or use PR squash merge (preferred)
gh pr merge --squash

Pattern 4: Find Who Changed a Line

# Blame file
git blame <file>
git blame -L 10,20 <file>  # Specific lines

# With gh
gh api repos/owner/repo/commits?path=<file> | jq '.[0]'

Pattern 5: Bisect to Find Bug

# Start bisect
git bisect start
git bisect bad  # Current commit is bad
git bisect good <commit>  # Known good commit

# Test each commit git presents
# ... run tests ...
git bisect good  # or bad

# When found
git bisect reset

Troubleshooting

Issue: Merge Conflicts

# 1. See conflicted files
git status

# 2. Resolve conflicts in each file
# ... edit files ...

# 3. Mark as resolved
git add <resolved-files>

# 4. Continue operation
git rebase --continue  # If rebasing
git commit             # If merging

Issue: Accidentally Committed to Wrong Branch

# 1. Create new branch from current state
git branch correct-branch

# 2. Reset current branch
git reset --hard HEAD~1

# 3. Switch to correct branch
git checkout correct-branch

Issue: Pushed Sensitive Data

# 1. Remove from history
git filter-branch --tree-filter 'rm -f <file>' HEAD

# Or use BFG Repo-Cleaner (better)
# bfg --delete-files <file>

# 2. Force push (coordinate with team!)
git push --force

# 3. Rotate any exposed secrets immediately

Issue: Need to Change Last Commit

# If not pushed yet
git commit --amend

# If already pushed (requires force push)
git commit --amend
git push --force-with-lease

WARNING: Only amend when:

1. User explicitly requested amend OR
2. Adding edits from pre-commit hook

Always check authorship before amending:

git log -1 --format='%an %ae'

Issue: PR Has Conflicts

# Option 1: Rebase on base branch
git fetch origin
git rebase origin/main
git push --force-with-lease

# Option 2: Merge base branch
git fetch origin
git merge origin/main
git push

# Option 3: Use gh CLI
gh pr update-branch 123

Git Safety Rules

1. Never force push to main/master: Warn user if requested
2. Never skip hooks: Don't use --no-verify unless explicitly requested
3. Never run destructive commands: Without user confirmation
4. Always check before amending: Verify authorship and push status
5. Use --force-with-lease: Instead of --force when needed

Worktree Gotchas

gh pr checkout is not worktree-safe

gh pr checkout operates against the main git directory regardless of the shell's current working directory — it doesn't respect "which worktree am I in." Running it from inside a worktree switches the main working directory's branch and overwrites files there, not the worktree you're standing in.

If a sub-agent needs to work on a PR branch inside a worktree, don't use gh pr checkout. Do this instead, run from inside the worktree:

git fetch origin <branch>
git checkout -b fix/<name> origin/<branch>

core.hooksPath is shared across all worktrees

core.hooksPath lives in the repo's shared .git/config — it is a single value, not per-worktree. If a sibling worktree runs husky init (or reinstalls husky), it can silently overwrite this value repo-wide with a path relative to its own worktree. Every other worktree's pre-commit hook then fires and does nothing — no error, the commit just lands as if lint-staged never existed.

Fix per worktree that needs isolated hooks:

git config extensions.worktreeConfig true
git config --worktree core.hooksPath <relative-path-to-hooks-dir>

Applies to any repo using git worktrees + husky (or any hooks manager that writes core.hooksPath), not just one project.

Diff and Patch Gotchas

git apply fails with "does not exist in index" — check diff.noprefix

This machine has diff.noprefix = true set globally in ~/.gitconfig (confirm with git config --get diff.noprefix) — it applies to every repo, not one project. It strips the a//b/ prefixes from diff headers, so patches look like:

--- projects/foo/bar.qmd
+++ projects/foo/bar.qmd

instead of the usual --- a/projects/foo/bar.qmd. git apply defaults to -p1 (strip one leading path component), which is correct for prefixed diffs but wrong here — it eats a real path segment (e.g. projects/) and produces "does not exist in index" or "does not exist on disk" even though the file is tracked at exactly that path.

Fix: always pass -p0 when applying a hand-crafted or sub-agent-generated diff on this machine — git apply --cached -p0 <patch> (no path stripping needed since the header is already relative to repo root). This is the standard fix for selective/partial-hunk staging (e.g. isolating one hunk of a file from other unrelated in-flight changes before a commit).

Recurred across unrelated repos (a standalone project repo, and the ~/workspace monorepo) because the root cause — a global gitconfig setting — wasn't written down after the first occurrence. Check diff.noprefix first before troubleshooting a "file not in index" apply failure; don't rediscover it by trial and error.

git commit -m "..." -- <pathspec> implicitly stages the full working tree for those paths

git commit -- <pathspec> is not "commit whatever's already staged, scoped to these paths" — it implicitly runs the equivalent of git add <pathspec> first, pulling in the current working-tree content of every listed path regardless of what was actually staged. In a shared/monorepo working tree with unrelated uncommitted changes sitting in the same files (a concurrent session's WIP, your own earlier unstaged edits), this can silently fold that unrelated content into a commit meant to be scoped to a specific change.

Near-miss: a sub-agent ran git commit -m "..." -- epq/charts.py tests/test_charts.py intending to commit only its own diff, but an unrelated in-progress feature sitting unstaged in the same files came along with it. Caught via git show --stat on the resulting commit before pushing; fixed non-destructively with git reset --soft HEAD^ (working tree untouched) followed by hand-staging just the intended hunks (git apply --cached against extracted patches, or git add -p).

Before any git commit -- <pathspec> on a file that might carry unrelated uncommitted content: stage explicitly first (git add -p or a hand-built patch), commit with a bare git commit (no pathspec) against the index, and verify with git show --stat/git diff --staged before it lands — don't rely on the pathspec argument to scope what gets committed.

Integration with Commit Message Writer

After validation and before committing:

# After all changes are ready
git add .
git status  # Review what will be committed
git diff --staged  # Review actual changes

# Then request commit using commit message writer agent
# Agent will:
# 1. Analyze changes
# 2. Draft professional commit message
# 3. Create commit with proper format
# 4. NO AI attribution (per CLAUDE.md)

Quick Reference

# Status and info
git status
git log --oneline
git diff

# Branches
git checkout -b <branch>
git push -u origin <branch>
git branch -d <branch>

# Commits
git add .
# (use commit message writer)
git push

# Pull requests
gh pr create
gh pr list
gh pr checkout 123
gh pr merge --squash

# Issues
gh issue create
gh issue list
gh issue view 123

# Sync
git pull --rebase
git fetch --prune

# Cleanup
git branch -d <branch>
git push origin --delete <branch>

Summary

Primary directives:

1. Always use commit message writer agent for commits
2. Use gh CLI for GitHub operations
3. Follow branch naming conventions
4. Keep commits atomic and clear
5. Never include AI attribution in commit messages
6. Be careful with destructive operations

Most common commands:

• git status - Check state
• git checkout -b <branch> - New branch
• gh pr create - Create PR
• git pull --rebase - Stay updated
• gh pr merge --squash - Merge PR