Merge Conflicts in .gitignore and an Auth Helper Kept Repeating

The session label we typed that morning read “reviewing the database for dev agents.” The commit trail at the end of the day said env system migration across twelve repos.

The ticket was workflow cleanup: an environment system and credential migration for the production app. It sounds like fifteen minutes of thoughtful editing and gets filed under housekeeping. That is what we expected to spend the day on. It is not what happened.

The env system and what tagged along with it

The production app is an older web application. We run it out of a fleet of long-lived Git clones on a Windows desktop. Each clone exists because the deployment workflow requires isolation. Each clone is also a time capsule of whatever state it was in the last time someone needed it.

The env system work was about standardizing how credentials flow into those clones during development. The old approach had grown inconsistent. Different clones had different .env file shapes, different variable names for the same credential, and no single document that said what the canonical layout was supposed to be. The credential migration was the other half: moving from the old shape to the new one, reliably, in a way that would survive contact with future hotfixes.

Together those two things are not complicated. Write the new layout. Write a migration checklist. Update the existing docs. Done.

That is what we thought we were doing until we counted the repos.

Twelve clones

The scope didn’t change dramatically. We ran the first migration pass on the primary development clone and it worked. Then we looked at the list of other repos that needed the same change. Twelve in total. Twelve long-lived forks, each with its own local drift, each carrying months of hotfixes and feature branches that had gone through without the migration.

Here is what long-lived drift means in practice. These are not twelve clean copies of the same codebase. Over years of parallel development, each clone has picked up divergence at the edges: local config, gitignore tweaks, files modified for a specific deploy context and never reconciled. The env system change was touching exactly those edges.

The pass on the primary clone was quick. Propagating and reconciling the same change across the fleet took the rest of the day.

The four sticky files

Merge conflicts kept coming, and they weren’t random. The same four files collided as the change moved from clone to clone: .gitignore, an authentication helper, a shared stylesheet-and-script include, and a shared includes file for a major feature area.

These are high-collision shared files: .gitignore, plus files near authentication, session state, and the includes pattern used across much of the application. If a branch touches how users log in or how pages assemble themselves, it touches those files.

The conflicts told us something the ticket description did not. The env system change wasn’t landing in neutral territory. It was landing on top of decisions each clone had made independently, and every conflict was a record of that drift.

We resolved each one. That part wasn’t difficult, but it meant reading the context for every conflict instead of taking an automatic resolution at face value. One wrong resolution in the shared includes file and a clone’s includes chain breaks silently until someone hits a page that depends on it.

The half nobody counts

The code part of the ticket was the env system itself and the credential migration. We shipped that. We also wrote a migration checklist, a migration doc, deployment doc updates, and a goals document for the change.

That documentation took real time. It was what made the migration repeatable instead of a one-time local repair.

A hotfix in a fleet like this has a life after the initial branch. The branch gets merged on one clone, tested, shipped. Six weeks later, someone needs to cut a hotfix from a different clone that hasn’t received the migration yet. Without the checklist, they hit the same drift problem from scratch with no map. Without the migration doc, they make a local decision that diverges from the canonical shape. Without the updated deployment docs, the next person who provisions a clean clone sets it up the old way.

The code change does the work once. The documentation is what makes it stick.

We have shipped hotfixes without the documentation. Every one of them left behind a small pocket of drift that the next person had to resolve by inference. This ticket was, in part, the cleanup from some of those earlier shortcuts.

What the commit trail says

The label was accurate for maybe the first ninety minutes. Then the env work began, the scope grew, and the work became what it became. The label never updated.

That matters because if we had summarized the day from the label, we would have misrepresented both the ticket and the work. The commit trail says: env system, migration checklist, migration docs, deployment doc updates, twelve clones, four sticky files, several hours of conflict resolution. The label says database review.

The right summary was in the commits.

Two things we do not know yet

First, whether the new env system can stay canonical across the fleet without spawning a permanent stream of merge-conflict tax. The standardization has to live somewhere. If it lives in files that every branch touches, every branch carries the conflict forward. The answer is probably to move the env layout out of the high-collision files and into dedicated, low-touch locations. That work wasn’t in this ticket.

Second, whether the checklist and migration docs actually reduce friction on the next hotfix, or go stale within two months and leave the next person worse off than if they had read the code directly. Documentation that isn’t maintained becomes misdirection. We don’t have a maintenance plan for these docs yet. That is a gap.

Both questions decide whether this was a durable fix or a one-time cleanup with a good write-up.

In a fleet of long-lived forks, a workflow ticket includes more than the code change. It includes the existing drift, the documentation, and the merge strategy. Next time, count the clones first, and decide who maintains the checklist and docs once the migration ships.

dxdev LESSON · paste into your AI coding agent
LESSON: env-drift-migration-tax
SOURCE: dxdev.com/blog/env-drift-migration-tax
WHAT HAPPENED: A credential and environment-system migration scoped for a single repo turned into a same-day, multi-repo operation because each long-lived clone had accumulated independent drift at the exact files the change needed to touch. The same migration that took twenty minutes on the primary clone took the rest of the day across the fleet. Four high-collision files surfaced repeatedly, each conflict a record of divergence that had never been reconciled. The documentation work (checklist, migration doc, deployment-doc updates) turned out to be as large as the code change itself, because without it the fix would dissolve into tribal knowledge before the next hotfix.
THE RULE: In a fleet of long-lived forks, every workflow change carries a drift tax; measure the fleet before you scope the ticket, and treat the docs as part of the fix, not overhead.
CHECK MY CODE, then report PASS / FAIL with file:line for each:
  1. Does any long-lived branch or clone skip reconciling shared high-collision files (gitignore, auth helpers, shared includes) during a cross-repo migration?
  2. Is there a canonical written source (checklist or migration doc) that a future engineer can follow to apply this change to a clone that has not received it yet?
  3. Does the migration touch low-traffic, dedicated config files rather than high-collision shared files that every feature branch modifies?
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.