Avoiding conflicts

Why this matters

Resolving conflicts is a skill; not having them is a habit. A team that merges small branches daily sees a conflict every few weeks. A team with month-old branches sees them constantly and dreads merging. The difference is entirely in how the work is organized, not in anyone's Git ability.

The habits that work

1. Keep branches short-lived. A branch merged within a day or two has almost nothing to conflict with. This single habit removes most conflicts, because a conflict needs two changes to the same lines in the same window of time.
2. Update from main often. Merge main into your branch daily (lesson 6.4). Ten small resolutions are easier than one large one, and each is fresh in everyone's memory.
3. One issue, one branch. A branch that touches the FAQ, the installation guide and the data file overlaps with three other people's work instead of one.
4. Pull before you start. Branching from a stale main guarantees you are working against a version that has already moved (lesson 5.8).
5. Push early and often. Colleagues can see what you are touching, and the merge request shows it before either of you is deep into the work.

Formatting habits, for prose

Documentation conflicts more than code, and two conventions remove most of it:

One sentence per line. Because Git compares lines, a paragraph written as one long line conflicts whenever two people touch it. The same paragraph with one sentence per line conflicts only when two people edit the same sentence:

Trailguide reads its data from a CSV file. You can add your own trails by appending a row. The columns are name, region, distance and difficulty.

Trailguide reads its data from a CSV file.
You can add your own trails by appending a row.
The columns are name, region, distance and difficulty.

Both render identically in Markdown, because Markdown joins consecutive lines into a paragraph. If the project uses this convention, follow it; if it does not, it is worth proposing.

Do not reflow paragraphs you are not editing. An editor that re-wraps at 80 characters on save turns a one-word change into a whole-paragraph change, which then conflicts with everyone. Turn that off for repositories that do not ask for it (lesson 4.6).

Append rather than insert, where the order does not matter. Two people adding entries to the end of a changelog conflict on the last line every time; two people adding to a list under their own headings do not. Some teams keep a CHANGELOG.d/ folder with one small file per entry, exactly to avoid this.

Coordinating without meetings

• Say what you are taking. A line in the issue or the team chat — "I'm rewriting the installation guide this afternoon" — costs nothing and prevents the expensive case: two people rewriting the same page in parallel.
• Look before you start. git fetch then git log --oneline origin/main -5, or the platform's recent-activity view, shows what is moving right now.
• Split by file, not by paragraph. If two people must work on the same document at once, agree that one takes the first half and the other the second, or split it into two files.
• Merge order matters for big changes. If a large restructuring is coming, get it merged first and let everyone rebase or merge onto it, rather than the other way round.

Do and don't

Common mistakes

• Long-lived branches with good intentions. The longer a branch lives, the more it conflicts and the more reluctant everyone is to merge it, which makes it live longer.
• Format-on-save in a repository without a formatter. Every file you open becomes a whole-file change.
• Waiting until the end to update from main. One enormous conflict instead of several small ones.
• Two people improving the same README paragraph on the same day without saying so.