Stacked branches
A stack is branches built on branches: feat/api off main, feat/ui off
feat/api. You work on all three, and when the bottom one lands the others
have to move.
Most tools that help with this keep a record — a file, a config entry, a note somewhere — saying which branch sits on which. Katari keeps no record. It works the relationship out from the commit graph every time you look.
Why that matters in practice
A record goes stale the moment you do something outside the tool that kept it. Rebase in a terminal, amend a commit, force-push, let a colleague restructure a branch — and the record now describes a shape the repository no longer has.
Because Katari derives the shape instead:
- It is right about a repository it has never opened before.
- It is right again after you rebase by hand, immediately.
- There is nothing to initialise, repair, or migrate.
- Nothing is written into your repository. Clone it elsewhere and the stacks are the same, because they were never stored in the first place.
Reading the panel
The left panel groups branches by where they stand:
| Group | |
|---|---|
| Trunk | The branch everything else is measured against — usually main. |
| In flight | Branches with work on them, nested under whatever they sit on. |
| Finished | Branches whose commits have already landed on trunk. |
A branch nested under another is one whose commits sit on top of that branch's commits. The nesting is the stack.
Branches that already landed
A branch is marked finished when its work is already on trunk — including when the merge squashed it, which leaves no commit in common to compare against.
That case is worth calling out because it is the one most tools get wrong. A squash-merge rewrites your commits into a single new one with a different hash, so a naive "is this branch an ancestor of trunk" check says no, and the branch sits in your list looking like live work for months. Katari compares the change itself rather than the commit identity, so a squashed branch is recognised as landed and can be deleted with confidence.
Restacking
When something below moves, the branches above it need replaying onto the new base. Restack does that, and the toolbar shows a count when any branch in the repository needs it.
Katari restacks by rebasing — the same operation you would run yourself. If there are conflicts you get the conflict screen, and the rebase continues or aborts from there.
Stale, and what it means
A branch marked stale has a base that has moved since the branch was last replayed onto it. It is not broken and nothing is lost; it means a restack would change something. The status bar counts them.