jj split UX is somewhat difficult to use

[chriskrycho]

I have been experimenting with using Jujutsu as my daily driver this month—and am writing up a long experience report on it, in hopes that it will be another small boost to Jujutsu (spoilers: I am a pretty big fan!). There is really only one area where I find jj to be a regression against Git, and that is around the behavior of jj split. The following is straight out of my WIP-writeup.

---

Jujutsu treats the working copy itself as a commit instead of having an “index” like Git. Git really only lets you break apart a set of changes with the index, using git add --patch. Jujutsu instead has a split command, which launches a diff editor and lets you select what you want to incorporate—rather like git add --patch does. As with all of its commands, though, jj split works exactly the same way on any commit; the working copy commit gets it “for free”.

Philosophically, I really like this. Practically, it is a slightly bumpier experience for me than the Git approach at the moment. Recall that I do not use git add --patch directly. Instead, I always stage changes into the Git index using a graphical tool like Fork. That workflow is slightly nicer than editing a diff—at least, as Jujutsu does it today. In Fork (and similar tools), you start with no changes and add what you want to the change set you want. By contrast, jj split launches a diff view with all the changes from a given commit present: splitting the commit involves removing changes from the right side of the diff so that it has only the changes you want to be present in the first of two new commits; whatever is not present in the final version of the right side when you close your diff editor ends up in the second commit.

If this sounds a little complicated, that is because it is. There are two big downsides to this approach, philosophically elegant though it is. First, I find it comes with more cognitive load. It requires thinking in terms of negation rather than addition, and the “second commit” becomes less and less visible over time as you remove it from the first commit. Second, it requires you to repeat the operation when breaking up something into more than two commits. I semi-regularly take a single bucket of changes on disk and chunk it up into many more than just 2 commits, though! That significantly multiplies the cognitive overhead.

The net is: when I want to break apart changes, at least for the moment I find myself quite tempted to go back to Fork and Git’s index. I do not think this problem is intractable, and I think the idea of jj split is right. It just—“just”!—needs some careful design work. Preferably, the split command would make it straightforward to generate an arbitrary number of commits from one initial commit, and it would allow progressive creation of each commit from a “vs. the previous commit” baseline. This is the upside of the index in Git: it does actually reflect the reality that there are three separate “buckets” in view when splitting apart a change: the baseline before all changes, the set of all the changes, and the set you want to include in the next commit. Existing diff tools do not really handle this—other than the integrated index-aware diff tools in Git clients!

---

Mostly hoping to kick off a discussion about this here:

1. Do other people have the same experience?
2. What might solutions look like?

[martinvonz]

I have been experimenting with using Jujutsu as my daily driver this month—and am writing up a long experience report on it, in hopes that it will be another small boost to Jujutsu (spoilers: I am a pretty big fan!).

Thanks!

I haven't read much of it yet, but I happened to notice that you said "so writing @-+-+ is the same as @". That's often correct, but not always, because the - and + operators return all parents/children. So if you're editing a merge commit, then - will include multiple parents, and if you do jj new foo-, then @-+ will include both foo and @. We should probably clarify that with examples in the doc.

By contrast, jj split launches a diff view with all the changes from a given commit present:

Technically, that actually depends on your "diff editor". The default diff editor of meld (like most regular diff tools) does present you with the full diff and you're expected to remove from it until you have the diff you want in the first commit. You might like scm-diff-editor better (see here for how to configure it).

I semi-regularly take a single bucket of changes on disk and chunk it up into many more than just 2 commits, though!

hg split does let you split into multiple commits in one go. A drawback of that is that you might lose a lot of work if you've performed a few splits and then accidentally quit the tool without saving. Doing only one split at a time reduces the amount of work you can lose. I think one reason hg split lets you do it because it can be slow to rebase the descendants. I think the fact that jj's rebasing is so much faster than hg's pretty much removes that argument from the equation. Still, I wouldn't be against an option for it.

[chriskrycho]

I haven't read much of it yet, but I happened to notice that you said "so writing @-+-+ is the same as @". That's often correct, but not always, because the - and + operators return all parents/children. So if you're editing a merge commit, then - will include multiple parents, and if you do jj new foo-, then @-+ will include both foo and @. We should probably clarify that with examples in the doc.

Noted; I'll update that section.

Technically, that actually depends on your "diff editor". The default diff editor of meld (like most regular diff tools) does present you with the full diff and you're expected to remove from it until you have the diff you want in the first commit. You might like scm-diff-editor better (see here for how to configure it).

Interesting; I will give it a try, but I have a long-standing bias against CLI-driven diff tools (I just don't like the experience of using them, generally speaking, as they tend not to have the affordances I am looking for in a well-behaved Mac app! Nothing more or less than that). Since the default experience most users will have is going to be via meld, kdiff, etc., it may still make sense to find some what to address the more fundamental thing I am getting at—as I wrote above: “the reality that there are three separate “buckets” in view when splitting apart a change: the baseline before all changes, the set of all the changes, and the set you want to include in the next commit.”

Granted: maybe I have just spent so long in Git land that it's hard for me to see; but that's part of what I have been giving it a good bit of time before opening this discussion. I felt this all pretty immediately but I wanted to see if it went away once I got used to it. It… has not.

hg split does let you split into multiple commits in one go. A drawback of that is that you might lose a lot of work if you've performed a few splits and then accidentally quit the tool without saving. Doing only one split at a time reduces the amount of work you can lose. I think one reason hg split lets you do it because it can be slow to rebase the descendants. I think the fact that jj's rebasing is so much faster than hg's pretty much removes that argument from the equation. Still, I wouldn't be against an option for it.

Yeah, that makes sense. I'm mulling on whether there's a way to keep the advantage of the "split" mechanic while also getting the advantages of something shipped like "progressively add changes from a baseline diff and commit; repeat until there are none there". Nothing comes to mind immediately, but if I come up with even a usable sketch I will share it here.

[arxanas]

You might like scm-diff-editor better (see here for how to configure it).

For future readers, the scm-diff-editor interface is now bundled directly in jj as the default diff editor, so you no longer need to do any manual setup.

[martinvonz]

Interesting; I will give it a try, but I have a long-standing bias against CLI-driven diff tools (I just don't like the experience of using them, generally speaking, as they tend not to have the affordances I am looking for in a well-behaved Mac app! Nothing more or less than that). Since the default experience most users will have is going to be via meld, kdiff, etc., it may still make sense to find some what to address the more fundamental thing I am getting at—as I wrote above: “the reality that there are three separate “buckets” in view when splitting apart a change: the baseline before all changes, the set of all the changes, and the set you want to include in the next commit.”

I was going to say that I don't think most tools allow 3-way diffing, but then I tried with Meld and it seems to do exactly what I want! I think we should change the "diff editor" interface to have a third view for the output instead of having the right side be the output, at least for tools that support it. That shouldn't be very hard to do. Thanks a lot for bringing this up! I really like the idea of presenting the diff in 3 tabs.

[chriskrycho]

Oh, neat—I had the same assumption and did not think to check it! I think my go-to (Kaleidoscope) will also handle that, though it looks like it'll need to be invoked as a "merge" rather than a diff—but I also expect that will resolve most tools' existing usage requirements.

As an aside: scm-diff-editor is a great tool to have handy: I still prefer the GUI editing, but as far as text-based diff editors go, it's good!

[ilyagr]

I was going to say that I don't think most tools allow 3-way diffing, but then I tried with Meld and it seems to do exactly what I want!

How did you invoke Meld? It's not immediately clear to me what this 3-way diff is, in particular I wonder what Meld pre-populates the output file with.

Or maybe you're proposing setting up a merge where the output file starts out as one of the sides? Which side? On the bright side, meld does seem to support "3-way folder comparison". I'm less sure about kdiff3 or others.

[ilyagr]

In any case, it should be straightforward to allow diff editor configs to have a $output parameter that causes jj to create a separate output directory for left and right. We could either have it always be populated with "right" content, or which side we start with could depend on which jj command is used.

[martinvonz]

How did you invoke Meld?

Simply meld <left> <middle> <right> (i.e. without -o or --auto-merge). Meld also understand when files have been marked readonly, so marking the left and right files readonly means that only the middle file can be edited, which is what we'd want.

[ilyagr]

I made a draft implementation of this in #2003, if you'd like to play with it.

[arxanas]

I think a jj commit --interactive command would be justified as well, as it might make the common case of simulating git add -p -> git commit a little easier.

Preferably, the split command would make it straightforward to generate an arbitrary number of commits from one initial commit, and it would allow progressive creation of each commit from a “vs. the previous commit” baseline

I've recounted to @martinvonz on a few occasions the Facebook UI for this (in Atom/VS Code):

• There's an infinite canvas (scrolling left-to-right) of commit editors.
  • You can add a new commit editor before or after any other one.
  • You can reorder commit editors (IIRC).
  • Then, you can move changed lines left or right between commits, rather than selecting them for inclusion in a binary manner.
  • Also, you can edit the commit messages in the same editors, rather than having to write them all at the end serially, which I think is quite useful.
• I checked and Sapling's sl web currently doesn't support this.

I have a branch locally embedding scm-diff-editor directly into jj (as it was intended to be used), with the hope that we could implement something like the above.

• Of course, it would be possible to specify an external mechanism for doing the same, but we'd have to define the command-line interface to talk to these kinds of "split-tools", and no other program currently supports such an interface, so embedding the library directly in jj and using the API seems easier.
  • Feel free to write the GUI tool yourself 😉.
• We could also use the embedding to do multi-file merge conflict resolution, as I believe there's no established command-line interface for this. (The Git mergetool interface only supports merging a single file at a time IIUC.)
• (Plus... competitive advantage because no other open-source VCS tool will support multi-way split 😎.)

[chriskrycho]

I like this overall description of a design flow, and I think designing a programmatic and CLI interface to it would enable this bit, which is not obviously a blocker now but could make for a really compelling feature (in both web UIs and dedicated editors) later.

Perhaps equally importantly, I think having a design to enable what the Atom/VS Code plugins from FB have done as a more general capability of the tool would go a long way to add a differentiation. Right now jj primarily feels like a better front-end to Git (and, you know: fair—in practice that's largely what it is so far!) but the potential is there to do things like this and make for a massively stronger sales pitch, because it's easy to demo—and demo-ability is an underrated aspect of how tools pick up steam. That can then (in principle! Who knows in practice?) give tools like Fork, Tower, etc. reasons they might want to think about supporting those capabilities/exposing them via GUIs/etc. and set up a virtuous cycle.

Starting with a direct embedding of scm-diff-editor sounds like an eminently reasonable way to figure out the rough edges of the APIs, what the hard bits are, etc.—and then leveraging that to figure out how to generalize it, etc.

Feel free to write the GUI tool yourself 😉.

…don't tempt me. 😂

[ilyagr]

Note: a lot of the plans discussed here are now implemented, see also #1905 (reply in thread).

[matklad]

+1 to the general idea that: jj split is the right idea, but poor ux, while git add --patch is the wrong idea, but with a bunch of sweet UX on top.

I've ended up recording a short 2 minute demo of the specific UI (magit) I personally need to be able to switch to jj:

https://youtu.be/kTAYEmbPsTM

[arxanas]

Thanks for posting, I added a discussion here arxanas/scm-record#63 for the built-in editor

[matklad]

I guess one extra thing for me is that I get to use my editor's shortcuts when navigating the diff. Things like "go to next half page", "recenter view", etc work in magit-status buffer the same way as in any other tex buffer.

But that's not really on jj, to be honest, rather, someone needs to do a jj plugin for Emacs (and VS Code (and Zed, which I am planning to switch to as soon as nixos unstable gets rust 1.79 🤣 ))