Merge main — sync feature branch with main

origin/main

Before You Start

• CLAUDE.md

  — check for the project's commit-message conventions and any post-merge validation steps.

• .github/

  or the project's CI config — identifies what CI expects after a merge (lockfile regen, codegen, ...).
• A clean working tree before starting. If there are uncommitted changes, this skill commits them first.

Step 1: commit current work

git status
git diff --stat

git add <specific-files>         # prefer listing files over `git add -A`
git commit -m "type(scope): concise message"

CLAUDE.md

.github/

type(scope): message

Step 2: fetch and measure distance

git fetch origin main
behind=$(git log --oneline HEAD..origin/main | wc -l)
ahead=$(git log --oneline origin/main..HEAD | wc -l)
echo "Branch is $behind commits behind and $ahead ahead of origin/main."

behind

Step 3: understand what changed on main

git log --oneline HEAD..origin/main
git diff --stat HEAD...origin/main

git diff --name-only HEAD...origin/main > /tmp/main_changes.txt
git diff --name-only origin/main...HEAD > /tmp/branch_changes.txt
comm -12 <(sort /tmp/main_changes.txt) <(sort /tmp/branch_changes.txt)

Step 4: merge

git merge origin/main

Step 5: resolve conflicts

git diff --name-only --diff-filter=U

1. Read the file — understand both sides of the conflict.
2. Read the main-side history —

   git log --oneline -5 origin/main -- <file>

   .
3. Decide resolution strategy:

• The conflict is in a generated/lock file (

  package-lock.json

  ,

  pnpm-lock.yaml

  ,

  uv.lock

  ,

  Cargo.lock

  ) — accept one side, then regenerate with the project's tool.
• The conflict is purely additive (both sides added different items to a list, import block, or config).
• The conflict is in a file you didn't intentionally change (formatting-only, auto-formatter drift).

• Both sides made substantive changes to the same function or class.
• The conflict involves architectural decisions.
• Business logic or test assertions are in conflict.

git add <resolved-file>

git commit                       # use the default merge message; do not amend

Step 6: post-merge validation

# Regenerate lockfile if the package manifest changed on main
# (pick the one your project uses)
# pnpm install    # if pnpm-lock.yaml was conflicted or package.json changed
# uv lock         # if uv.lock was conflicted
# cargo check     # validates Cargo.toml + Cargo.lock

# Re-run lint/typecheck to catch merge mistakes
# (use the project's command from Quick Reference in CLAUDE.md)

git add <regenerated-files>
git commit -m "chore: post-merge regen after syncing with main"

Step 7: verify

review-diff

Critical Rules

• Never force-push after merging. The merge commit is permanent.
• Do not

  git rebase

  a branch that's been pushed. This skill does merge. If the project mandates rebase, use a different skill — not this one.
• Do not silently drop one side of a conflict. If both sides made real changes, ask the user.
• Always commit before merging — uncommitted work gets clobbered.
• Use the default merge commit message; don't amend it.

Verify

# No conflicts remain
git status
# Expected: "nothing to commit, working tree clean" (or only the merge commit)

# Branch is now up to date with origin/main
git log --oneline HEAD..origin/main | wc -l
# Expected: 0

# Lint/typecheck passes (project-specific command from CLAUDE.md)

Common Mistakes

git merge