Git Advanced Skill

TEMPLATE: This skill uses YOUR_VALUE tokens. Replace with your project values before use.

Purpose

Provide guidance for advanced git operations with safety considerations. This project uses a rebase-first workflow with linear history -- understand these patterns to avoid breaking the codebase.

When This Skill Applies

• Rebasing feature branches onto dev
• Using git bisect to find bugs
• Cherry-picking commits between branches
• Resolving complex merge conflicts
• Recovering from git mistakes

Stop-the-Line Conditions

FORBIDDEN Operations

# FORBIDDEN: Force push to protected branches
git push --force origin main     # NEVER
git push --force origin master               # NEVER

# FORBIDDEN: Merge commits on dev branch
git merge feature-branch                     # Use rebase-and-merge PR strategy

# FORBIDDEN: Skip pre-commit hooks
git commit --no-verify                       # Hooks exist for a reason

# FORBIDDEN: Rewriting shared history
git rebase -i HEAD~5 && git push --force     # If already pushed

SAFE Operations

# SAFE: Force-with-lease on your feature branch
git push --force-with-lease origin TASK-XXX-feature

# SAFE: Interactive rebase before first push
git rebase -i origin/main

# SAFE: Force push after conflict resolution on your own branch
git rebase origin/main && git push --force-with-lease origin TASK-XXX-feature

Rebase Workflow (Standard)

Before Creating PR

# 1. Fetch latest changes
git fetch origin main

# 2. Rebase onto latest
git rebase origin/main

# 3. If conflicts, resolve them
git status                   # See conflicted files
# ... edit files to resolve ...
git add <resolved-files>
git rebase --continue

# 4. Push with force-with-lease
git push --force-with-lease origin TASK-XXX-feature

During PR Review (After Feedback)

# 1. Make requested changes
git add . && git commit -m "fix: address PR feedback [TASK-XXX]"

# 2. Fetch and rebase again
git fetch origin main
git rebase origin/main

# 3. Push update
git push --force-with-lease origin TASK-XXX-feature

Git Bisect (Finding Bugs)

When to Use

Use bisect when you know a bug was introduced at some point but do not know which commit.

Bisect Workflow

# 1. Start bisect
git bisect start

# 2. Mark current state (has bug)
git bisect bad

# 3. Mark a known good commit
git bisect good <commit-sha>

# 4. Git checks out middle commit - test it
{{TEST_UNIT_COMMAND}}  # or manual test

# 5. Tell git if this commit is good or bad
git bisect good  # or
git bisect bad

# 6. Repeat until found
# Git will tell you the first bad commit

# 7. End bisect
git bisect reset

Automated Bisect

# Run a test script automatically
git bisect start HEAD abc1234
git bisect run {{TEST_UNIT_COMMAND}}

Cherry-Pick (Selective Commits)

When to Use

• Backporting a fix to an older branch
• Pulling a specific commit from one branch to another
• Selective feature extraction

Cherry-Pick Workflow

# 1. Find the commit SHA
git log --oneline branch-name | head -20

# 2. Cherry-pick to current branch
git cherry-pick <commit-sha>

# 3. If conflicts, resolve them
git status
# ... resolve conflicts ...
git add <resolved-files>
git cherry-pick --continue

# 4. Push the result
git push origin current-branch

Cherry-Pick Multiple Commits

# Range of commits (oldest..newest, exclusive of oldest)
git cherry-pick abc123^..def456

# Specific commits
git cherry-pick abc123 def456 ghi789

Conflict Resolution

Common Conflict Scenarios

Conflict Resolution Steps

# 1. See what's conflicted
git status

# 2. Open conflicted file, look for markers
<<<<<<< HEAD
your changes
=======
their changes
>>>>>>> branch-name

# 3. Edit file to resolve (remove markers, keep correct code)

# 4. Mark as resolved
git add <resolved-file>

# 5. Continue rebase/merge
git rebase --continue

Conflict Prevention

# Rebase frequently to avoid large conflicts
git fetch origin main
git rebase origin/main  # Do this daily during long features

# Check for potential conflicts before rebase
git diff origin/main...HEAD --stat

Recovery Commands

Abort Operations

git rebase --abort
git merge --abort
git cherry-pick --abort

Undo Last Commit

# Keep changes staged
git reset --soft HEAD~1

# Keep changes unstaged
git reset HEAD~1

# Discard changes (DANGEROUS)
git reset --hard HEAD~1

Recover Lost Commits

# Find lost commits in reflog
git reflog

# Restore to a specific state
git reset --hard HEAD@{n}

# Cherry-pick a lost commit
git cherry-pick <sha-from-reflog>

Safety Guidelines

When to Ask Before Force Push

ALWAYS ask first if:

• You have pushed commits that others might have pulled
• You are working on a shared branch
• You are not 100% sure what will happen
• The branch has been open for > 1 week

Safe Force Push Pattern

# 1. Verify you're on correct branch
git branch

# 2. Verify what will be pushed
git log origin/TASK-XXX-feature..HEAD --oneline

# 3. Use force-with-lease
git push --force-with-lease origin TASK-XXX-feature

Pre-Push Checklist

• run your test suite passes
• On correct branch (not protected branch)
• Commits have proper message format
• No sensitive data in commits

Related Skills

• safe-workflow: Complete workflow patterns
• release-patterns: PR and merge patterns
• CONTRIBUTING.md: Branch naming and commit format