git-conflict-resolution

name	git-conflict-resolution
description	Reference material for resolving git merge and rebase conflicts. Covers conflict marker anatomy, resolution strategies by file type, context gathering, and rules for correct resolution.

Git Conflict Resolution

Reference for the resolve-conflicts session command. Covers how to read, understand, and resolve git conflicts correctly.

Conflict Marker Anatomy

A conflict block in a file looks like this:

<<<<<<< HEAD
// Code from the current branch (ours)
const timeout = 5000;
=======
// Code from the incoming branch (theirs)
const timeout = 10000;
>>>>>>> feature-branch

Marker	Meaning
<<<<<<< HEAD	Start of the current branch's version (ours)
=======	Separator between the two versions
>>>>>>> {ref}	End of the incoming branch's version (theirs)

During a merge: "ours" is the branch you're on, "theirs" is the branch being merged in.

During a rebase: "ours" is the branch you're rebasing onto, "theirs" is the commit being replayed (your branch's changes). This is the reverse of merge — your own changes appear as "theirs."

Resolution Strategies by File Type

Code Files

1. Read git log for both refs to understand the intent behind each side's changes
2. Read surrounding code (imports, related functions, tests) for semantic context
3. Merge the logic from both sides — do not blindly pick one side
4. If one side is a strict superset of the other (e.g., one side added a feature, the other made a small fix), take the superset and apply the fix
5. If both sides modified the same function differently, understand what each change achieves and write a version that incorporates both intents
6. Verify the resolved code compiles logically (matching braces, correct imports, no duplicated declarations)

Lock Files

Lock files (package-lock.json, pnpm-lock.yaml, yarn.lock) cannot be meaningfully merged:

1. Delete the conflicted lock file
2. Run the appropriate package manager to regenerate:
   • npm install for package-lock.json
   • pnpm install for pnpm-lock.yaml
   • yarn install for yarn.lock
3. Stage the regenerated file

Generated Files

Files that are generated by tooling (compiled output, auto-generated code, bundled assets):

1. Delete the conflicted file
2. Run the generation command
3. Stage the result

Config Files

Configuration files (tsconfig.json, .eslintrc, docker-compose.yml, etc.):

1. Compare both versions structurally
2. Prefer the more complete version — the one with more entries or newer settings
3. If both sides added different entries, include all entries from both sides
4. Validate JSON/YAML syntax after resolution

Context Gathering

Before resolving, gather context to make informed decisions:

1. Git log: git log --oneline -10 {base_ref} and git log --oneline -10 {incoming_ref} — understand what each branch was doing
2. Related files: read files imported by or related to the conflicted file
3. Project conventions: check CLAUDE.md and .claude/rules/ for project-specific patterns
4. Tests: check if either side added tests that reveal the intended behavior

Rules

1. Never leave conflict markers — every <<<<<<<, =======, >>>>>>> must be removed
2. Resolve all conflicts in one pass — do not leave any files partially resolved
3. Stage immediately — git add each file right after writing the resolution
4. Lock files: always regenerate — never attempt to merge lock file contents
5. Fail on true ambiguity — if both sides make valid but contradictory changes and there is no way to determine the correct resolution from context, report failure rather than guess
6. Do not commit — the caller (merge/rebase function) handles the commit or rebase continuation
7. Verify with git diff --check — confirm no conflict markers remain after resolution