Git Workflow Expert

Git Workflow Expert

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)
• Resolving merge conflicts (especially complex multi-file conflicts)
• Rebase workflows (interactive rebase, rebase onto, autosquash)
• Cherry-picking across branches
• Using git bisect to find bug-introducing commits
• Recovering lost work with reflog
• Monorepo git patterns (sparse checkout, subtree, submodules)
• Cleaning up messy git history
• Setting up git hooks for quality gates
• Force push safety and shared branch protocols

NOT for:

• GitHub Actions / CI/CD pipelines (use github-actions-pipeline-builder)
• 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

---

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

---

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 commits
if ! grep -qE "^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .+" "$1"; then
  echo "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)

1. 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.

2. 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

3. 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)

4. 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

---

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"

---

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

Advanced Rebase Patterns

Deep dives for complex rebase scenarios that go beyond basic git rebase main.

---

Rebase --onto (Transplant Commits)

When you branched from feature-a but now want your commits on main:

# Situation: feature-b was branched from feature-a
# main --- A --- B (feature-a)
#                \--- C --- D (feature-b, you are here)

# You want: main --- C' --- D' (feature-b, rebased onto main)
git rebase --onto main feature-a feature-b

# This says: take commits between feature-a and feature-b,
# and replay them onto main

Multi-level --onto

# Rebasing a sub-feature onto a new base after upstream was rebased
git rebase --onto new-base old-base current-branch

---

Rebase Conflict Strategies

Strategy 1: Ours/Theirs During Rebase

During a rebase, "ours" and "theirs" are REVERSED from merge:

• --ours = the branch you're rebasing ONTO (e.g., main)
• --theirs = YOUR commits being replayed

# Accept the upstream version for a specific file during rebase
git checkout --ours package-lock.json
git add package-lock.json
git rebase --continue

Strategy 2: rerere (Reuse Recorded Resolution)

# Enable globally
git config --global rerere.enabled true

# Now git remembers how you resolve conflicts
# Next time the same conflict appears, it auto-resolves

# See recorded resolutions
git rerere status
git rerere diff

# Forget a bad resolution
git rerere forget path/to/file

Strategy 3: Abort and Decompose

When a rebase has too many conflicts:

git rebase --abort

# Instead of rebasing 20 commits at once, do it in chunks:
git rebase -i HEAD~20
# Mark the first 5 as "pick", the rest as "pick"
# Save. Resolve conflicts for just those 5.
# Then rebase the next batch.

---

Autosquash Workflow

The fastest way to clean up work-in-progress commits:

# While working, create fixup commits:
git commit --fixup abc123       # Will be squashed into abc123
git commit --fixup :/"Add auth" # Match by commit message substring

# When ready to clean up:
git rebase -i --autosquash main

# fixup! commits automatically arrange themselves
# Just save the editor and they squash in order

Squash vs Fixup

• git commit --squash abc123 — Squashes AND lets you edit the final message
• git commit --fixup abc123 — Squashes AND keeps the original message (most common)

---

Preserving Merge Commits During Rebase

# By default, rebase flattens merge commits
# To preserve them:
git rebase --rebase-merges main

# This recreates the merge structure on the new base
# Useful for feature branches that had their own sub-branches

---

Rebase Safety Checklist

1. Am I the only one pushing to this branch? If no → DON'T REBASE 2. Do I have uncommitted changes? If yes → git stash first 3. Is the rebase complex (&gt;10 commits)? If yes → make a backup branch first: git branch backup-feature 4. Have I fetched recently? git fetch origin before rebasing onto remote branches 5. Do I know reflog? If yes → you can always recover. If no → learn it before complex rebases.

Monorepo Git Strategies

Patterns for managing large repositories with multiple packages, services, or teams.

---

Performance at Scale

Problem: Large Repos Are Slow

Git operations slow down with:

• Many files (&gt;100K): git status takes seconds
• Large history (&gt;100K commits): git log, git blame slow
• Large objects (binaries, ML models): clone takes forever

Solutions

# Partial clone (skip blobs until needed)
git clone --filter=blob:none https://github.com/org/monorepo.git

# Shallow clone (truncate history)
git clone --depth=1 https://github.com/org/monorepo.git

# Sparse checkout (only work on your packages)
git sparse-checkout init --cone
git sparse-checkout set packages/my-service shared/

# Git maintenance (schedule background optimization)
git maintenance start
# Runs: prefetch, loose-objects, incremental-repack, pack-refs

Filesystem Monitor (FSMonitor)

# Enable Watchman integration for faster git status
git config core.fsmonitor true
git config core.untrackedcache true

# On macOS, also:
git config core.fsmonitor.hookversion 2

---

CODEOWNERS

# .github/CODEOWNERS

# Global — catch-all reviewers
* @org/platform-team

# Package-specific
/packages/auth/     @org/auth-team
/packages/billing/  @org/billing-team
/packages/ui/       @org/design-system-team

# Specific files
package.json        @org/platform-team
tsconfig.base.json  @org/platform-team

# CI/CD
/.github/workflows/ @org/devops-team

---

Path-Based CI Triggers

GitHub Actions

on:
  push:
    paths:
      - 'packages/auth/**'
      - 'shared/types/**'
  pull_request:
    paths:
      - 'packages/auth/**'
      - 'shared/types/**'

Turborepo-Aware

# Only test affected packages
npx turbo run test --filter=...[HEAD~1]

# Show what packages changed
npx turbo run build --dry-run --filter=...[main...HEAD]

---

Branch Protection in Monorepos

Per-Path Branch Protection (GitHub)

GitHub doesn't natively support per-path branch protection. Workarounds:

1. CODEOWNERS + Required Reviews: Different teams for different paths 2. Rulesets (GitHub 2024+): Path-based restrictions 3. CI Status Checks: Per-package test jobs that only run when their paths change

Recommended Setup

# Required status checks:
# - packages/auth: auth-tests must pass
# - packages/billing: billing-tests must pass
# - global: lint, typecheck must always pass

---

Commit Conventions for Monorepos

Conventional Commits with Scope

feat(auth): add PKCE support for OAuth flow
fix(billing): correct proration calculation for annual plans
docs(ui): update Button component API reference
chore(deps): bump TypeScript to 5.4

Scopes map to package names. This enables:

• Automated changelogs per package
• Version bumping only affected packages (Changesets, Lerna)
• Filtering git log by package: git log --oneline -- packages/auth/

---

Submodule Alternatives

Migrating FROM Submodules

# Convert submodule to subtree
git submodule deinit libs/shared
git rm libs/shared
rm -rf .git/modules/libs/shared

# Re-add as subtree
git subtree add --prefix=libs/shared https://github.com/org/shared.git main --squash

---

Large File Handling

Git LFS

# Install and enable
git lfs install

# Track file patterns
git lfs track "*.psd" "*.sketch" "*.zip" "models/*.bin"

# Check what's tracked
git lfs ls-files

# Migrate existing large files to LFS
git lfs migrate import --include="*.bin" --everything

Cost Warning

Git LFS has storage and bandwidth limits on GitHub. For ML models (&gt;1GB), consider:

• DVC (Data Version Control) — pointers in git, data in S3/GCS
• Hugging Face Hub — purpose-built for model versioning
• Artifact registries — separate from git entirely