Discussion on "One Index, Many Writers: Avoiding Git Merge Conflicts with Deterministic Write Areas"

Oliver Zehentleitner · 2026-09-09T18:32:32.614Z

While working on Keep the Why, I ran into a very ordinary Git problem. There is one shared context/index.md. Developers and coding agents can add new context files in different branches. The changes a

The interesting part is that this treats Git conflicts as a write-allocation problem, rather than trying to make the merge process smarter. Pre-allocating deterministic regions gives independent writers different merge anchors, which is especially useful when agents are making changes concurrently.

I also like the agent-retrieval side effect. Predictable sections reduce the search space before an agent has to load the actual context, so the same structure improves both merge behavior and retrieval efficiency. It’s a good example of a small repository convention solving what initially looks like two separate problems.

Exactly - that’s the part I found most interesting as well.

Once I stopped looking at it as a merge problem and started looking at it as a write-allocation problem, the solution became much simpler.

And yes, the retrieval benefit for agents was a nice side effect rather than the original goal. I like solutions where one bit of structure helps both humans/tools and Git without introducing another layer of infrastructure.

Thanks for putting it that clearly!

Nice write-up, Oliver. The "sparse index with delayed writers" framing really clicked for me. It also explains why the headings work so well mechanically: Git's three-way merge conflicts on overlapping or even adjacent changes, and each heading guarantees at least one untouched line between write points.

One question: within a section, are new entries sorted, or inserted directly under the heading? With the latter, any two same-letter additions would still collide. That matters because first letters aren't evenly spread, especially for software topics (api, auth, cache, ci, config...), so C and S will probably run hot.

Also, since agents love to "tidy" files (removing empty headings, re-sorting, turning lists into tables), a small CI check that all 36 headings exist and each entry sits under the right one might be what keeps the convention alive long term.

Would love to see numbers on this at some point. git merge-tree --write-tree makes it pretty easy to simulate append vs. sorted vs. sectioned.

Great points.

Yes, entries are sorted by filename within each section. So two additions under the same letter can still collide if they land in the same gap - especially while that section is sparse. As it fills up, the existing entries themselves create more natural merge anchors. So the 36 headings don't eliminate conflicts, they mainly remove the worst case where every new entry competes for the same append position.

And funny enough, the “agents will tidy this away” problem is already covered too. The current spec + keep-the-why-lint check that all 36 headings exist, entries are under the correct heading, and entries are sorted (E205, E206, E204). I learned pretty quickly not to rely on an agent politely respecting formatting conventions. :)

I really like the git merge-tree --write-tree idea. A comparison of append vs. globally sorted vs. sectioned would be worth measuring - ideally also with a deliberately skewed filename distribution rather than uniform random data.

That might become a follow-up to the article. Thanks!

Search Hashnode

One Index, Many Writers: Avoiding Git Merge Conflicts with Deterministic Write Areas

Responses(4)