Master git operations from daily workflow to disaster recovery. Covers branching strategies, merge vs rebase decisions, conflict resolution, monorepo patterns, and advanced operations that most developers never learn but desperately need.
When to Use
Use for:
Choosing a branching strategy for a project (trunk-based, GitHub Flow, git-flow)
PR review process and checklists (use code-review-checklist)
GitHub API / webhooks / repository management
Git LFS setup (mention it, but not the core focus)
Core Decision: Branching Strategy
flowchart TD
Start[New project or rethinking strategy?] --> Team{Team size?}
Team -->|Solo or 2-3| Trunk[Trunk-Based Development]
Team -->|4-15| GHFlow[GitHub Flow]
Team -->|15+ or regulated| Q2{Release cadence?}
Q2 -->|Continuous deploy| GHFlow
Q2 -->|Scheduled releases| GitFlow[Git-Flow]
Q2 -->|Multiple supported versions| GitFlow
Trunk --> T1[Main branch only]
T1 --> T2[Short-lived feature branches < 1 day]
T2 --> T3[Feature flags for incomplete work]
GHFlow --> G1[main + feature branches]
G1 --> G2[PR-based review]
G2 --> G3[Deploy from main after merge]
GitFlow --> GF1[main + develop + feature + release + hotfix]
GF1 --> GF2[Formal release branches]
GF2 --> GF3[Hotfix branches from main]
Strategy Comparison
Dimension
Trunk-Based
GitHub Flow
Git-Flow
Branch lifetime
Hours
Days
Days-weeks
Merge frequency
Multiple/day
Daily
Per-sprint
CI requirement
Mandatory
Strong
Optional
Rollback mechanism
Feature flags
Revert commit
Release branch
Best for
High-trust teams
Most web projects
Versioned releases
Worst for
Junior-heavy teams
Multiple live versions
Fast iteration
Merge vs Rebase Decision
flowchart TD
Q[Integrating changes?] --> Shared{Is the branch shared?}
Shared -->|Yes, others push to it| Merge[Use merge]
Shared -->|No, only me| Q2{Want clean history?}
Q2 -->|Yes| Rebase[Use rebase]
Q2 -->|No, preserve context| Merge
Rebase --> Q3{Long-lived branch?}
Q3 -->|Yes, many conflicts expected| RebaseOnto[Consider rebase --onto]
Q3 -->|No| RebaseSimple[Simple rebase]
Anti-Pattern: Rebase Shared Branches
Novice: "I'll rebase main into the shared feature branch to keep it clean."
Expert: Never rebase branches others are pushing to. Rebase rewrites commit SHAs — anyone who already pulled will get duplicate commits and merge hell. Use merge for shared branches, rebase for personal branches.
Detection: Multiple developers report "weird duplicate commits" after a pull.
Anti-Pattern: Merge Commit Soup
Novice: "I'll just merge main into my feature branch every morning to stay current."
Expert: Daily merge commits from main create an unreadable history. Instead: git rebase main on your personal branch (one clean operation), or if you must merge, at least squash when merging back to main.
Timeline: Before 2020, merge was the default. Modern teams prefer rebase for feature branches, merge (or squash-merge) for PRs.
Conflict Resolution
The Calm Approach
# 1. Before resolving: understand what happened
git log --merge --oneline # Show conflicting commits
git diff --name-only --diff-filter=U # List conflicted files# 2. For each file: understand both sides
git diff :2:file :3:file # :2 = ours, :3 = theirs# 3. Resolve, then verify
git add resolved-file.ts
git diff --cached # Review what you're about to commit# 4. After all files resolved
git merge --continue# or git rebase --continue
Anti-Pattern: Accept Ours/Theirs Blindly
Novice: "This conflict is too complex, I'll just git checkout --ours . and be done."
Expert: Blindly accepting one side loses the other person's work. If a conflict is genuinely too complex, use a 3-way merge tool (git mergetool) to see base + ours + theirs simultaneously. For large-scale conflicts, consider rerere (reuse recorded resolution) to cache conflict solutions.
Detection: Features mysteriously disappear after merges.
Advanced Operations
Cherry-Pick Workflow
# Pick a specific commit from another branch
git cherry-pick abc123
# Pick a range (exclusive start, inclusive end)
git cherry-pick abc123..def456
# Cherry-pick without committing (stage only)
git cherry-pick --no-commit abc123
# If conflicts: resolve then
git cherry-pick --continue
When to cherry-pick: Hotfixes that need to go to multiple release branches. Bug fixes from a feature branch that's not ready to merge.
When NOT to: If you need many commits, merge or rebase instead. Cherry-pick creates duplicate commits with different SHAs.
Git Bisect (Find Bug-Introducing Commit)
# Start bisect
git bisect start
git bisect bad # Current commit is broken
git bisect good v1.2.0 # This tag was working# Git checks out a middle commit. Test it, then:
git bisect good # or: git bisect bad# Repeat until git identifies the first bad commit# Automated bisect with a test script:
git bisect start HEAD v1.2.0
git bisect run npm test# Runs test at each step automatically
Reflog Recovery (Undo Almost Anything)
# See recent HEAD positions
git reflog --oneline -20
# Recover a dropped stash
git stash list # Empty? Check reflog:
git fsck --no-reflogs | grep commit # Find dangling commits
git show <sha> # Inspect to find your stash# Undo a bad rebase
git reflog
# Find the SHA before the rebase started
git reset --hard HEAD@{5} # Reset to that point# Recover deleted branch
git reflog | grep "branch-name"
git checkout -b recovered-branch <sha>
Interactive Rebase (Clean History)
# Rewrite last 5 commits
git rebase -i HEAD~5
# In the editor:# pick abc123 Add user model ← keep as-is# squash def456 Fix typo in user model ← squash into previous# reword ghi789 Add auth ← edit commit message# drop jkl012 WIP debugging ← remove entirely# edit mno345 Add migration ← pause to amend# Autosquash: commits prefixed with "fixup!" or "squash!" auto-arrange
git commit --fixup abc123 # Creates "fixup! Add user model"
git rebase -i --autosquash HEAD~5 # Automatically squashes it
Monorepo Git Patterns
Sparse Checkout (Work on Subset)
# Enable sparse checkout
git sparse-checkout init --cone
git sparse-checkout set packages/core packages/cli
# Now only packages/core and packages/cli are checked out# Other directories exist in git but aren't on disk
Subtree (Embed Another Repo)
# Add a subtree
git subtree add --prefix=libs/shared https://github.com/org/shared.git main --squash
# Pull updates
git subtree pull --prefix=libs/shared https://github.com/org/shared.git main --squash
# Push changes back upstream
git subtree push --prefix=libs/shared https://github.com/org/shared.git feature-x
Submodules vs Subtree
Dimension
Submodules
Subtree
Model
Pointer to external repo
Copy of external repo
Clone
Requires --recurse-submodules
Just works
Update
git submodule update
git subtree pull
CI complexity
Higher (need init step)
Lower
Best for
Large vendored deps
Small shared libs
Footgun risk
High (detached HEAD trap)
Low
Git Hooks for Quality
# .git/hooks/pre-commit (or use husky/lefthook)#!/bin/sh# Run linter on staged files only
npx lint-staged
# .git/hooks/commit-msg#!/bin/sh# Enforce conventional commitsif ! grep -qE "^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .+""$1"; thenecho"Commit message must follow Conventional Commits format"exit 1
fi# .git/hooks/pre-push#!/bin/sh# Run tests before push
npm test || exit 1
Anti-Pattern: Skipping Hooks
Novice: "The pre-commit hook is slow, I'll just --no-verify."
Expert: If hooks are too slow, fix the hooks (use lint-staged for incremental linting, parallelize tests). --no-verify becomes a habit that defeats the purpose. If you truly need to skip once (emergency hotfix), document why in the commit message.
Branching Strategy Selection Logic
When the user asks which branching strategy to use, apply these rules in order:
Hard constraints (override everything)
Multi-version library (hasMultipleVersions: true AND isLibrary: true) → git-flow
Reasoning: Maintaining v2.x hotfixes while developing v3.x requires long-lived release branches. Trunk-based cannot serve two audiences.
Migration from trunk-based: Create release/vN.x branches from the last tag on each major. Backport via cherry-pick.
Regulated industry (isRegulated: true) → git-flow
Reasoning: Auditors expect named release branches with approval gates, a clear trail from commit to production, and the ability to point at a branch and say "this is what shipped." Trunk-based can technically satisfy this with tags, but the audit conversation is easier with git-flow.
Note: If CI maturity is high AND the compliance team is open to it, trunk-based with deploy tags + signed commits is superior. But assume the compliance team is not open to it.
CI maturity gate
Low CI maturity (ciMaturity: 'low') → github-flow
Reasoning: Trunk-based without comprehensive CI means broken code on main. GitHub Flow (feature branches + PR review + merge) provides a human safety net. Recommend investing in CI, then graduating to trunk-based.
Migration to trunk-based later: Shorten branch lifetimes to <1 day, add branch protection requiring green CI, then drop the requirement for PR approval on small changes.
Default (most teams)
Everything else → trunk-based
Reasoning: Smallest feedback loops, least merge pain, forces good CI habits. Feature flags handle incomplete work. Short-lived branches (<1 day) are acceptable as a concession.
If team is >15 people: Consider trunk-based with short-lived feature branches (still trunk-based — the branch lives <24h and auto-deletes after merge).
Migration paths
From
To
Steps
git-flow → trunk-based
1. Merge develop into main. 2. Delete develop. 3. Set branch protection on main (require CI green). 4. Adopt feature flags for incomplete work. 5. Shorten branch lifetime target to <1 day.
git-flow → github-flow
1. Merge develop into main. 2. Delete develop and all release/* branches. 3. PR directly to main. 4. Tag releases from main.
github-flow → trunk-based
1. Reduce PR size to <200 lines. 2. Add comprehensive CI. 3. Allow direct push to main for trivial changes. 4. Keep PRs for larger changes but merge same-day.
Force Push Safety
# NEVER force push to main/master# Use --force-with-lease instead of --force
git push --force-with-lease origin feature-branch
# --force-with-lease checks that remote hasn't been updated# since your last fetch. Prevents overwriting others' work.# Set as default (never use bare --force again):
git config --global alias.pushf "push --force-with-lease"
PR template with checklist, reviewers, and CI requirements
Git hooks config (Husky + lint-staged) for pre-commit and pre-push validation
Conflict resolution guide with step-by-step procedures for common scenarios
Release workflow defining tagging, changelog generation, and deployment triggers
References
references/advanced-rebase-patterns.md — Consult for complex rebase scenarios: rebase --onto, interactive rebase strategies, handling rebase conflicts in long-lived branches
references/monorepo-git-strategies.md — Consult for monorepo-specific patterns: sparse checkout optimization, CODEOWNERS, path-based CI triggers, large repo performance
