--- title: "Discussion on \"One Index, Many Writers: Avoiding Git Merge Conflicts with Deterministic Write Areas\" | Hashnode" description: "Discussion on \"One Index, Many Writers: Avoiding Git Merge Conflicts with Deterministic Write Areas\". How a small structural change reduced unnecessary Git conflicts in a shared Markdown index — and made it easier for coding agents to navigate." url: "https://hashnode.com/posts/one-index-many-writers-avoiding-git-merge-conflicts-with-deterministic-write-areas/6aa1a640f3a6f898eb822819" --- [Feed](https://hashnode.com/feed) / Discussion # [One Index, Many Writers: Avoiding Git Merge Conflicts with Deterministic Write Areas](https://blog.technopathy.club/one-index-many-writers-avoiding-git-merge-conflicts-with-deterministic-write-areas?utm_source=hashnode&utm_medium=feed) How a small structural change reduced unnecessary Git conflicts in a shared Markdown index — and made it easier for coding agents to navigate. Sep 9 · 4 min read · blog.technopathy.club Read the article - [#git](https://hashnode.com/tag/git) - [#github](https://hashnode.com/tag/github) - [#gitlab](https://hashnode.com/tag/gitlab) - [#devsecops](https://hashnode.com/tag/devsecops) - [#aiengineering](https://hashnode.com/tag/aiengineering) - [#codingagents](https://hashnode.com/tag/codingagents) - [#software-architecture](https://hashnode.com/tag/software-architecture) - [#developer-tools](https://hashnode.com/tag/developer-tools) - [#opensource](https://hashnode.com/tag/opensource) - [#mergeconflicts](https://hashnode.com/tag/mergeconflicts) - [#keepthewhy](https://hashnode.com/tag/keepthewhy) ## Written by [Oliver Zehentleitner](https://hashnode.com/@oliver-zehentleitner) @oliver-zehentleitner · Vienna, Austria [View profile](https://hashnode.com/@oliver-zehentleitner) DevSecOps · Python · AI-driven Development · Real-world findings from production systems. I build systems that work — technically sound, security-first, and actually useful to the people who depend on them. Creator of the UNICORN Binance Suite — six open-source Python libraries with 3.3M+ downloads and 390+ dependent public projects — and Keep the Why, an open-source agent skill that preserves the reasoning behind engineering decisions alongside the code. Currently pioneering AI-driven open-source maintenance: running a controlled AI agent that maintains production code and documenting what this shift means for engineering teams. Vienna, Austria 🇦🇹 ## Responses 4 Markdown supported · ⌘↵ to post [Mateo Ruiz](https://hashnode.com/@mateoruiz) [Sep 10](https://hashnode.com/posts/one-index-many-writers-avoiding-git-merge-conflicts-with-deterministic-write-areas/6aa1a640f3a6f898eb822819/comment/6aa2352d029e60c5a8f074e6) 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. [Oliver Zehentleitner](https://hashnode.com/@oliver-zehentleitner) [Sep 10](https://hashnode.com/posts/one-index-many-writers-avoiding-git-merge-conflicts-with-deterministic-write-areas/6aa1a640f3a6f898eb822819/comment/6aa2352d029e60c5a8f074e6#reply-6aa23b9c218ce5989bd1a95a) 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! [Sneha M K](https://hashnode.com/@snehamk) [Sep 11](https://hashnode.com/posts/one-index-many-writers-avoiding-git-merge-conflicts-with-deterministic-write-areas/6aa1a640f3a6f898eb822819/comment/6aa3cda512f0e36080c9836e) 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. [Oliver Zehentleitner](https://hashnode.com/@oliver-zehentleitner) [Sep 11](https://hashnode.com/posts/one-index-many-writers-avoiding-git-merge-conflicts-with-deterministic-write-areas/6aa1a640f3a6f898eb822819/comment/6aa3cda512f0e36080c9836e#reply-6aa3d13f26f46c06ed3ea52a) 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!