My multi-repo workflow used to be a nightmare of detached HEADs

跑个benchmark891 Beginner 1d ago 83 views 5 likes 2 min read

Coming from a mono-repo background, I tried to play nice with standard Git submodules, but it was a disaster. I wanted the organizational benefits of a mono-repo with the flexibility of individual repositories, but every tool I tried felt like it had too much baggage. I eventually realized that if I wanted a tool that actually got out of my way, I had to build it.

I ended up using Claude, Codex, and Gemini to help architect "GWZ" (Git Workspace Zone). It's a CLI tool that essentially lets you treat a collection of member repositories as a single workspace when you need to, without breaking the underlying Git logic.

Here is how it handles the "multi-repo vs. mono-repo" tension:

Repository Integrity: Member repos stay as standard Git repositories. You don't get those annoying submodule side effects unless you explicitly ask to materialize a specific tag or snapshot.

Workspace State: It uses "snapshots" and "commit markers" stored in the root repo. This allows you to recover the exact state of your entire workspace, which is basically a lifesaver for debugging cross-repo dependencies.

Familiar Command Surface: The CLI mimics Git. You use gwz status, gwz diff, gwz add, gwz pull, etc. It feels like Git, but it's operating on the workspace level.

Member Management: It includes specific commands like gwz repo create, gwz sync, and gwz detach.

The "Forall" Power: There is a forall command that lets you run a command across all selected member repos simultaneously. This is a massive productivity boost for bulk operations.

One technical detail that surprised me was the implementation. While I usually stick to Python or C++, this was built in Rust. The developer (myself) needed a decoupled architecture where the "core" engine is a separate crate from the CLI. This makes the engine embeddable and wire-friendly, rather than just being a terminal script.

A weirdly cool byproduct of using LLMs to help write the documentation and code was the inclusion of a --json / --jsonl output flag. The LLMs "suggested" this because it provides much better context for AI agents reading the output. It’s basically a tool designed to be used by both humans and LLM agents in an AI workflow.

Current Status:

It's a bit rough around the edges UX-wise, but it's functional.

The codebase (across the CLI and Python variants) has 764 tests with about 82% line coverage.

If you are doing heavy multi-repo work, this is a much more stable alternative to managing complex submodule trees.

Documentation is available here: