The nature of our work is changing. Software development is no longer a chain-of-thought code-it-all process, but increasingly is a work of coordinating, directing and selecting. Beagle is a git-compatible revision control system that tunes the underlying git model to this new reality. This short post is one of the series on How Beagle Works.
The way I work now can be very messy, having tens of in-flight worktrees is very much the norm. Some are waiting for a blocker, others need some more thinking, yet more are lower priority batches waiting for their turn. In this environment, sorting things out can be challenging. Some say, agents can do that, but in my experience, some amount of steering is necessary to get anything but a random result, and commit/merge gates are certainly the place to do so.
The minimal situational awareness is what the status command reports, so let's talk about that. The state of a file can be, in the first approximation, one of four:
.↑●∅That only reflects the difference between the worktree and its base commit; unchanged worktree is exactly the base. But the state of a file in Beagle actually involves four trees:
The tracked tree is typically our upstream, so it has a lot of value to know whether something changed in there, to avoid any unnecessary rebases, etc. We keep an eye on the upstream at all times!
The patch-in thing is the way Beagle does merges and rebases. The idea is that blindly merging synthetic tree states (merges and rebases) is bad-bad-bad because no one actually checked them. The idiomatic loop is get-change-test-post. Hence, any other trees get merged in by the patch command, then edited, tested, and eventually committed with the post command. The worktree is like a cauldron where you put your ingredients to make your stew.
What does it mean in practice though? It means, a file can be in one of 256 states of dirtiness. How? For the base tree and the tracked tree, there is their recentmost common ancestor tree (aka "root"). So, any file in the base, tracked or patched-in tree can be in one of four states: same, changed, created, deleted. Plus, there are local changes, relative to the base tree. That produces 4**4=256 shades of a file being somewhat changed. Like: committed, but not pushed yet. Or: freshly committed. Or: locally edited and patched by a merge, but not committed yet.
These are all crucial states that one may want to check. But, can we invent 256 terms (adjectives?) to use them consistently? Sure no.
For that reason, Beagle expresses that quad-state as four colored chars:
That explains the picture:
status uses the same four slots (track-base-patch-work) to describe the commit delta between the trees; a commit is ✔ checked in every tree that has it already.
This kind of awareness certainly helps when navigating two levels of in-progress worktrees locally on my laptop, all upstreamed to the main trunk tree. Just 104 worktree dirs, not much. No branches, no stable/testing/edge, YOLO all around.