A merge conflict is Git asking a person to decide how overlapping changes should combine. Practice once in a disposable repository, with a clean working tree, before deadlines or team work make the decision stressful.
Create a controlled conflict
Use a new practice repository with no important files. Commands assume a recent
Git installation and a default branch named main; adjust the branch name only
if your repository uses another one.
Create plan.md:
# Project plan
Priority: accuracy
Commit it. Create a branch named short-deadline, change the priority to
speed, and commit. Return to main, change the same line to clarity, and
commit.
Now merge:
git merge short-deadline
Git cannot infer whether the result should say speed, clarity, accuracy, or a new combination, so it stops.
Inspect before editing
Run:
git status
git diff
The file will contain markers similar to:
<<<<<<< HEAD
Priority: clarity
=======
Priority: speed
>>>>>>> short-deadline
The markers show two competing versions. They are not intended to remain in the finished document. Read surrounding context and both branches before choosing.
Git’s official git merge documentation
explains that Git marks conflicts in the working tree; after resolution, you
stage the result and continue or commit. It also documents git merge --abort
and warns that starting with non-trivial uncommitted changes can make
reconstruction difficult.
Resolve meaning, not markers
Edit the line to a deliberate result:
Priority: clarity under the agreed deadline
Remove all conflict markers, read the complete file, and run the appropriate check. For code, compile or test. For structured data, parse it. For prose, render or reread the affected section.
Then:
git add plan.md
git status
git diff --staged
git merge --continue
Depending on configuration, Git may open an editor for the merge message. Inspect the final history and file.
Know when to abort
Abort when you started from the wrong branch, do not understand the intended result, discover unrelated changes, or need help from the people who authored the work. Aborting is a valid decision, not failure.
Do not use broad destructive commands copied from an AI or search result. Record the current state and ask for repository-specific help.
Common mistakes
- Choosing “ours” or “theirs” without reading meaning.
- Deleting markers but losing valid content from one side.
- Resolving generated output instead of its source.
- Continuing without tests.
- Starting a merge with unexplained local changes.
- Assuming the conflict is the only possible semantic problem.
Do this now
Perform the practice conflict from beginning to end. Then repeat it and abort instead of resolving. Explain what state each command changed.
Log what you learned
Record only:
- Result: What did the action produce?
- Evidence: What observation, test, or source supports that result?
- Next action or unresolved question: What should happen next?
Next, document a project so another person can install, run, test, and verify it.