DEV Community

Pulkit
Pulkit

Posted on

I let the compiler enforce that every action in my Git TUI has a CLI equivalent

For the early part of my career I lived in VS Code, and the part I was genuinely attached to was the source control panel. Not the editor, not the extensions. The staging model: one list showing what is staged and what is not, so I could see exactly what was going into a commit before I made it.

Then the agentic CLI tools arrived and I started living in my terminal instead. I wanted that panel back, so I built it. Quinjet is a Git interface for the terminal, written in Rust on ratatui.

This post is about the one rule that ended up shaping the whole codebase, and the twenty lines that keep it true.

The rule

Every user-visible repository or GitHub operation in the terminal interface is also reachable from a command-line verb.

If you can press a key to do it, you can type a command to do it. Stage a file, create a branch, pop a stash, cherry-pick, revert, resolve a conflict: all of it has a verb.

That sounds like a nice-to-have. It is actually the difference between a tool you use and a tool you can build on. A TUI is a dead end for automation. The moment you want the same thing in a script, in CI, or in an agent loop, you are back to raw git and reimplementing whatever the interface was doing for you.

Why rules like this rot

I have written this rule into a README before. It does not survive contact with a deadline.

What happens is ordinary. You are in the UI, adding a feature. You need an operation the CLI does not have yet. You add it to the UI path because that is the file you have open, and you tell yourself you will add the verb after. Six weeks later the UI can do eleven things the command line cannot, and nobody can tell you which eleven.

A README cannot catch that. A code review will catch it the first three times and then stop. The only thing that reliably catches it is the build.

The shape that makes it enforceable

The enforcement only works because of a structural decision made earlier, so that part first.

There is exactly one command vocabulary. Command names every operation, Outcome names every answer, and Session::execute is the only thing that runs them. Repository mutations are a GitOperation enum inside that vocabulary.

The important consequence is what the TUI's background worker does, which is nothing interesting:

use crate::cli::{Command, Outcome, Session};
Enter fullscreen mode Exit fullscreen mode

The worker builds no argument lists and spawns no git. It takes a Command, hands it to a Session, tags the answer with the generation its caller asked under, and sends it back. The terminal UI is a client of the same API the command line is a client of. There is no second path to Git for a feature to hide in.

So "every operation has a verb" reduces to a question a compiler can answer: does every GitOperation variant name a path in the clap command tree?

The twenty lines

macro_rules! operation_routes {
    ($($pattern:pat => $sample:expr => [$($path:literal),+];)+) => {
        const fn verb_for(operation: &GitOperation) -> &'static [&'static str] {
            match operation {
                $($pattern => &[$($path),+],)+
            }
        }

        #[test]
        fn every_operation_the_interface_performs_has_a_verb() {
            let operations = [$($sample),+];
            for operation in &operations {
                let path = verb_for(operation);
                assert!(
                    resolves(path),
                    "the operation names the verb {path:?}, \
                     which the command tree does not have"
                );
            }
            let kinds: HashSet<_> =
                operations.iter().map(std::mem::discriminant).collect();
            assert_eq!(
                kinds.len(),
                operations.len(),
                "every operation variant must have one route fixture"
            );
        }
    };
}
Enter fullscreen mode Exit fullscreen mode

One invocation declares the whole mapping. Each line is a pattern, a sample value, and the verb path:

operation_routes! {
    GitOperation::Stage(_)      => GitOperation::Stage(Vec::new())   => ["stage"];
    GitOperation::StageAll      => GitOperation::StageAll            => ["stage"];
    GitOperation::Unstage(_)    => GitOperation::Unstage(Vec::new()) => ["unstage"];
    GitOperation::Checkout(_)   => GitOperation::Checkout(String::new())
                                                       => ["branch", "switch"];
    GitOperation::StashPop(_)   => GitOperation::StashPop(None)   => ["stash", "pop"];
    GitOperation::CherryPick(_) => GitOperation::CherryPick(String::new())
                                                       => ["cherry-pick"];
    // ...
}
Enter fullscreen mode Exit fullscreen mode

It is worth being precise about what each of the three pieces catches, because they fail at different times and for different reasons.

The match catches the variant you forgot. It is exhaustive over &GitOperation, so adding a variant without adding a line here is a non-exhaustive match.

I wanted to be sure rather than believe my own README, so I added a junk variant and ran the compiler:

pub(crate) enum GitOperation {
    ProveTheMacroWorks,
    Stage(Vec<PathBuf>),
    // ...
Enter fullscreen mode Exit fullscreen mode
error[E0004]: non-exhaustive patterns:
              `&git::GitOperation::ProveTheMacroWorks` not covered
  --> src/git/operations.rs:10:15
  --> src/git/mod.rs:228:15
  --> src/cli/tests/routes.rs:21:23
Enter fullscreen mode Exit fullscreen mode

Three sites, and they are not the same kind of thing, which turned out to be the part worth writing down.

The first two are ordinary code. perform is the match that actually runs the operation, so it forces you to implement the thing. label is the progress string the UI shows while it runs, so it forces you to name it in human words. Both are in the normal build: cargo build fails.

The third is verb_for, which lives behind #[cfg(test)]. That one does not block cargo build, only cargo test, and it breaks at compile time rather than at assertion time. You get E0004 naming the variant you did not route, rather than a test that happened to be looking in the right place.

That third site is the whole point. The first two were going to stop you anyway, because an operation that does not run is obviously broken. An operation with no CLI verb runs perfectly and ships. It is exactly the kind of omission that survives review, and it is the one the macro exists to make impossible.

It also costs nothing at runtime, for the straightforward reason that none of it is in the runtime: verb_for is a const fn over &'static [&'static str].

The test catches the verb that does not exist. resolves walks the real clap tree, the same one the binary ships:

fn resolves(path: &[&str]) -> bool {
    let root = Cli::command();
    let mut command = &root;
    let mut found = Vec::new();
    for name in path {
        let Some(child) = command.find_subcommand(name) else {
            return false;
        };
        found.push(child);
        command = found.last().unwrap();
    }
    true
}
Enter fullscreen mode Exit fullscreen mode

The found vector is there to keep each borrowed subcommand alive while command points at it, which is the usual price of walking a borrowed tree.

So you cannot satisfy the compiler by writing => ["stage"] next to an operation whose subcommand you never built. The claim is checked against the shipped command tree rather than against a list someone maintains by hand.

The discriminant set catches the lazy copy-paste. The failure mode the first two miss is adding a variant and silently pointing its fixture at an existing one, which makes the match exhaustive while quietly testing the same operation twice. Collecting std::mem::discriminant into a HashSet and comparing lengths means every variant contributes exactly one fixture.

Three mechanisms, roughly twenty lines, and the rule now holds whether or not anyone remembers it.

What it bought

The obvious payoff is that --json is a global flag. Every verb takes it, because every verb is the same Command rendered through a different emitter. src/cli/render.rs writes plain text with no terminal, no color, and no width assumption, and the JSON path is one document per invocation.

The less obvious payoff is that a few readings grew a --watch flag almost for free, since a watch loop is just a Session read on a timer:

quinjet pr checks 42 --watch
Enter fullscreen mode Exit fullscreen mode

On a terminal that repaints. Under --json it emits one compact document per read. Redirected, it appends frames. The CI log tails while the run is still going, which matters because the GitHub Actions job endpoint serves whatever a job has written so far, so repeating the read is what tailing is.

And the thing I did not expect: the rule made the codebase easier to reason about rather than harder. There is one place where Git happens. When a repository operation misbehaves, there is exactly one file to open.

What it costs

The honest part. The rule has a boundary, and the boundary is a judgement call that no macro checks for you.

Presentation state is explicitly out of scope: focus, scrolling, folding, filtering, mouse capture. Those are UI concepts and they stay in the app. Nobody wants quinjet scroll --down 3.

Drawing that line correctly is the actual design work, and it is still manual. The compiler only enforces the rule once you have decided what counts as an operation. Get that wrong and you get a perfectly enforced version of the wrong rule.

It also adds friction in exactly the moment described earlier, which is the point. Adding a UI feature now means adding a verb, a Session arm, a plain-text rendering, a clap subcommand, a route fixture and a docs page. Six steps instead of one. That friction is the feature, but you should know you are buying it.

Not solved

Partial hunk staging is not in. Staging is per file: stage, unstage, stage all, unstage all. The diff view can jump between hunks with [ and ], but that is navigation, not selection. It is on the list alongside multi-repository actors, non-UTF-8 path preservation and a real three-way merge editor.

Which, for a tool whose whole origin is the VS Code staging panel, is a slightly uncomfortable thing to admit in public. It is the next thing I am building.


Quinjet is MIT, written in Rust, and installs with Homebrew, apt, Winget, cargo or a one-line script.

If you try it, I would like to know what breaks, especially on large repositories and unusual fork setups.

Top comments (0)