glossary

Git Merge Conflict

A situation where git cannot automatically reconcile two divergent changes to the same part of a file, requiring manual resolution by the developer.

explanation

Merge conflicts occur when two branches modify the same line of a file differently, or when one branch deletes a file while the other modifies it. Git marks the conflicting region in the file with conflict markers (<<<<<<<, =======, >>>>>>>) showing both versions, and the developer must edit the file to produce the correct final state before staging and committing the resolution. Conflict resolution is a manual, context-sensitive process. The developer examines both versions, considers the intent of each change, and produces a merged result that satisfies both purposes. This may involve choosing one side, combining elements from both, or writing entirely new code. Tools like mergetool (vimdiff, meld, Beyond Compare) provide three-way merge views showing the base, local, and remote versions. The frequency of merge conflicts is a measure of team coordination and code architecture. Well-modularised codebases where teams work on distinct files experience fewer conflicts. Frequent conflicts in the same files often indicate poor separation of concerns or insufficient communication about ongoing work.

examples

# Conflict markers in a file

<<<<<<< HEAD

const TIMEOUT = 5000;

=======

const TIMEOUT = 30000;

>>>>>>> feature/timeout-config

git merge --abort # abort the merge and return to pre-merge state

git diff --name-only --diff-filter=U # list unmerged files

git mergetool # launch the configured merge tool

how git-agent helps

git-agent reduces merge conflicts by producing atomic commits that are scoped to specific files and logical changes. Smaller, focused commits are less likely to touch the same lines as other work, and when conflicts do occur, the clear commit messages help you understand the intent of each side's change.

brew install gitagenthq/brew/git-agent

FAQ

Can git-agent resolve merge conflicts automatically?

No. git-agent is a commit authoring tool, not a merge conflict resolver. Merge conflicts require human judgment about the intent of each change. However, git-agent's detailed commit messages provide valuable context for making those decisions.

What is the best strategy to avoid merge conflicts?

Frequent integration with the target branch, small focused commits, modular code architecture, and clear team communication. Rebasing feature branches on main before opening PRs also reduces conflicts at merge time.

What is the difference between a merge conflict and a rebase conflict?

The conflict resolution process is the same (edit the markers, stage, continue). The difference is that a merge conflict happens once at the merge commit, while a rebase conflict can happen multiple times as each commit is reapplied individually.

Git rebase Atomic commits Git cherry-pick