The One-Line Correction That Saved a Git History

Subject message: [user] do not do commits in parallel

In the midst of a sprawling coding session spanning hundreds of messages, dozens of files, and a complex distributed systems architecture, a single six-word instruction from the user arrives with disproportionate weight. The message is terse, almost abrupt: "do not do commits in parallel." To an outsider, it might read as a minor stylistic preference. But within the context of this session—where the assistant has just dispatched multiple autonomous subagents to create git commits simultaneously—this correction represents a crucial moment of architectural discipline, one that reveals deep assumptions about version control, collaboration, and the nature of clean engineering practice.

The Context: A Firehose of Parallel Agent Work

To understand why this message was written, we must first understand what preceded it. The session had been building toward a major milestone: completing the three-layer horizontally scalable S3 architecture for a Filecoin Gateway system. The architecture required stateless S3 frontend proxies on port 8078, independent Kuri storage nodes with isolated RIBS keyspaces, and a shared YugabyteDB backend with per-node keyspaces for blockstore data and a shared keyspace for S3 object routing.

In message 559, the user gave a multi-part instruction. The test cluster was broken—port 9010 returned "connection refused" and port 8078 returned "internal server error." The user listed bugs to fix: update the S3 schema, add a multipart uploads table, implement health check endpoints and node identification headers. But critically, the user added: "But first - make commits for all changes so far. Use agents for everything even if not really needed - this will save top level context."

The assistant interpreted "use agents for everything" as a mandate to parallelize aggressively. And so it did. In messages 560 and 561, the assistant dispatched no fewer than seven concurrent agent tasks, each tasked with creating a separate git commit for a different slice of the codebase: configuration changes, interface changes, Kuri S3 plugin changes, kuboribs dual CQL connection changes, the s3frontend package, build system changes, and test-cluster infrastructure. Each agent ran independently, each created a commit, and each reported success.

Why "Do Not Do Commits in Parallel" Matters

The user's correction lands immediately after seeing this flurry of parallel commits. The reasoning is subtle but critical. When multiple commits are created in parallel from the same starting point, they all share the same parent commit. The resulting git history is a star topology—multiple branches of equal age diverging from a single point, with no clear ordering among them. This creates several problems:

First, linear history is lost. A reader trying to understand the evolution of the codebase cannot trace a clean narrative through the commits. Was the configuration change made before or after the interface change? The git log provides no answer because they were created simultaneously. For code review, bisecting bugs, or understanding dependencies, this ambiguity is costly.

Second, dependency ordering is obscured. Some of these commits logically depend on others. The kuboribs dual CQL connection commit depends on the configuration commit that introduced S3CqlConfig. The s3frontend package commit depends on the interface commit that added NodeID and ExpiresAt to S3Object. When commits are siblings rather than a chain, these dependencies are invisible in the history.

Third, the assistant's parallel approach undermines the very reason the user asked for commits in the first place. The user wanted commits to "save top level context"—to checkpoint progress before moving on to fix bugs. But parallel commits create a messier context, not a cleaner one. A future developer (or the same developer returning after a week away) would face a tangled history that obscures rather than illuminates the architecture's evolution.

Assumptions Made and Corrected

The assistant made a reasonable but incorrect assumption: that "use agents for everything" meant maximum parallelism, including for git operations. This assumption conflated two different kinds of parallel work. Using agents for code review, analysis, or exploration is indeed beneficial—it saves context and accelerates discovery. But using agents for git commits introduces a different kind of cost: the cost of disordered history.

The assistant also assumed that git commits are independent artifacts that can be created in any order. In reality, commits are nodes in a directed acyclic graph. Their relationships matter. A commit is not just a snapshot of changes; it is a statement about the sequence in which those changes were made. Parallel commits erase that sequencing information.

The user's correction implicitly teaches an important lesson: parallelism is a tool, not a goal. The right question is not "can I do this in parallel?" but "should I do this in parallel?" For git commits, the answer is almost always no, because the value of a commit history lies in its linear narrative, not in the speed with which commits were created.

The Thinking Process Visible in the Correction

The user's message is remarkable for what it reveals about their mental model. They are not just managing the assistant's output; they are actively monitoring the process by which work is done. The user noticed the parallel commits not because they caused an immediate error (the commits succeeded), but because they violated a principle of clean engineering practice. This is the mark of an experienced developer who has internalized the importance of commit hygiene.

The brevity of the message—just six words, no explanation—is itself telling. The user trusts that the assistant (and by extension, anyone reading the conversation) will understand the reasoning without needing it spelled out. It is a correction delivered with the confidence of someone who knows that the principle is self-evident once stated. There is no anger, no frustration, no lengthy justification. Just a clear, direct instruction that reorients the work.

Input and Output Knowledge

To understand this message, the reader needs to know: that the assistant was using subagents to create commits; that multiple commits were being created simultaneously from the same branch state; and that git history is a directed acyclic graph where commit ordering matters. The reader also needs to understand the broader context: that the session was checkpointing progress before moving to bug fixes, and that clean history was a prerequisite for that checkpointing to be useful.

The knowledge created by this message is both practical and conceptual. Practically, it establishes a workflow rule: commits must be sequential, not parallel. Conceptually, it reinforces the idea that engineering artifacts (like git history) have intrinsic structure that must be respected, and that parallelism is not always an optimization.

Conclusion

"do not do commits in parallel" is a six-word masterclass in engineering discipline. It is a correction that, once applied, prevents a subtle but real degradation of the project's historical record. In a session filled with complex architectural decisions, database schema migrations, and distributed system debugging, this simple instruction stands out as a reminder that the quality of a codebase is not just about what the code does, but about how the story of its creation is told. A clean git history is not a luxury; it is a form of communication with every future developer who will read, review, and debug this code. And sometimes, preserving that communication requires saying "no" to parallelism, even when parallelism is the easiest path forward.