Kristoffer Balintona — #VCS

Jujutsu (jj) VCS workflows and the convenience of its “operation log”

Thu, 27 Mar 2025 08:35:00 GMT

Over the last month or two I’ve been trying out the relatively new jujutsu version control system (VCS) — and loving it. At first, I discovered it and read their GitHub README with curiosity but skepticism. Then I sought a few YouTube videos^[1] demonstrating jj in action, and a tutorial for a text-based reference. I became very interested. I initialized a jj repo in one of my small git projects and played around. Since then, I’ve migrated all of my personal repositories to jj, and use jj for practically everything.

From the time I’ve spent with jj, I’ve felt myself sliding into some general workflows:

A jj squash workflow
In git, this would be a workflow where you make a commit and continually amend/extend that commit until its intended goal is completed.
1. Make progress toward a desired goal.
2. Commit (jj commit, or jj new then jj describe -m "...") with a message describing this unit of work.
3. Continue making changes.
4. Squash (perhaps interactively: jj squash -i^[2]) new changes until the desired goal is accomplished.
5. Maybe change the description of the previous commit commit.
Work in the working copy
1. Envision a goal for a new commit. Express that into the description of the working copy commit: jj describe -m "...".
2. Work until much of that goal is met.
3. jj new to work on the next goal. Or jj split -i if some of the changes in the working copy belong in the next commit.
4. jj edit to hop between commits and work on each until completion. Perhaps jj new -A ... one or more times when when you don’t want certain changes in a commit: make changes across however many of those commits, then jj squash them all into your original commit when you’re happy. (You’re basically creating a new git branch!)
Concurrent commits workflow
Work on several commits simultaneously, using combinations of jj squash, jj new, and jj rebase to make make reversible changes while having a clean jj log at the end. In essence, this is point (3.4) above but with room for added complexity.

I’m not a VCS expert, and my projects are small, but I’ve gravitated to (1) and (2) without feeling any mental strain of keeping track of where this and that change is and what CLI operations avoid x problem or y merging conflict (which, by the way, jj permits! Jujutsu treats conflicts as first-class, so conflicts and their resolutions percolate through ancestors and descendants without problem.)^[3]

Perhaps the most exciting part of using jj is fearlessly making changes and experimenting. This has been an extraordinary boon for my learning about how to use jj in accordance to its VCS concepts. The reason is jj’s operation log (jj op log) and the ability to revert back to any past repository state (jj op restore OPERATION_ID).

With jj op restore, I can merge branches, create conflicts, resolve conflicts, mess up… then go back as if it never happened. I can make sweeping repository changes without fear! In git, I’d be walking on egg shells, worried about the potential to ruin the entire state of my local repository if I’m not careful…

I’d definitely recommend trying jj out if you haven’t already! Easily turn a git repo into a jj repo with a git backend: jj git init \-\-colocate.

A surprising upside to vc-dir marks over magit

Wed, 27 Nov 2024 04:40:00 GMT

Vc.el is Emacs’s built-in interface for version control CLI tools. With respect to Git, magit has for several years now been the most favored (with respect to popularity) Git^[1] interface. At least in the r/emacs subreddit, magit is frequently considered a killer-feature—an irreplaceable feature unique to Emacs.

For the most part I am inclined to agree. However, in the last few months, I’ve been regularly experimenting using vc. This is in part motivated by recent improvements to vc’s implementation of Git, and another part motivated by a curiosity to see whether I’d end up enjoying some parts of the vc-way of doing things over the magit-way of doing things.^[2]

On such insight has been the surprising benefits of calling vc-dir instead of magit-status.

The nicety of `vc-dir` marks §

In magit-status, I would typically stage various files and hunks and commit them when ready. vc does not use Git’s “staging” concept (because not all version control systems use such a concept). So instead, to achieve something analogous, a user might call vc-dir (or, much more commonly for me, project-vc-dir), mark edited files (or entire directories!) using vc-dir-mark (m), and check out (commit) those changes via vc-next-action (v) or see a diff of those changes with vc-diff (=) and commit the changes in that diff-mode buffer (v).^[3]

A problem for the magit interface, however, is visual clarity when it comes to focusing on changes in a certain subset of files. For example, sometimes I am working with changes in files within a single directory alongside many other uncommitted changes elsewhere in the repository. To make a commit with magit, I would need to navigate past or fold changed hunks/files I want to ignore. With many unstaged changes this means many files to ignore. This leads to a significant reduction in visual clarity since I end up having to ignore more files than I’m currently working on.

There is a subtle solution in vc.el. The secret lies in the fact that marks, which can be used to selectively create diff buffers and commit changes from those buffers, are preserved in vc-dir buffers after changes are committed. A mark is only removed once the corresponding line is removed via something like vc-dir-hide-up-to-date (x) or vc-dir-kill-line (C-k). Marks are magical because they let me focus on the files relevant to my current work: I can mark the files and directories I am focusing on then call vc-next-action in the vc-dir buffer to commit changes only in those files and directories (or, if I want to be selective about the hunks I commit: first call vc-diff to see the diff of just the marked files, kill/remove the hunks I don’t want to commit, then vc-next-action).Then I can write more changes and make more commits in the same way. (Furthermore, while this vc workflow might seem like it would necessarily involve many more keystrokes, I found this not to be the case under certain scenarios.)

In short, with vc.el, a really efficient workflow is

vc-diff or vc-root-diff → vc-next-action and
vc-dir (with persistent marks) → vc-diff → vc-next-action.

The latter is unique to vc.el, and a feature I don’t think the magit UI can replicate. So while magit can sometimes become visually cluttered, vc-dir marks let users focus on their current work by easily excluding from view files and directories one is not concerned with currently.

A caveat §

Historically, I’ve found this especially fruitful when working on my literate Emacs config^[4] (wherein any “single change” involves changes to the .org file as well as the resulting tangled file(s)) and Emacs packages. Still, I think I prefer magit in cases where the staging functionality of Git is crucial. For instance, I have a repository that houses all my org notes and org-agenda files. There are frequently many changes for this repository, so the convenience of staging/unstaging has been crucial for me. In cases like these, I haven’t found an equivalent for vc.el yet.

Changelog §