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.

[rmacklin]

@chriskrycho what you wrote about "progressively add changes from a baseline diff and commit; repeat until there are none there" completely resonates with me, as I feel there are times where it's more productive to focus exclusively on a burst of coding and then later switch to "VCS mode" where you work from that "code burst" result to progressively create multiple atomic commits.

I realize this post is rather old now, so I'm curious how you feel about things currently. Do you still yearn for this? Have you gotten used to the other way of working? Have you crafted workarounds that let you work in that way?

(One workaround I wonder about is "leaning into the git compatibility" and just using a git add --patch (or equivalent) workflow for this specific use case - sounds a bit taboo, but perhaps it's functional?)

[martinvonz]

I skimmed this thread and I don't quite understand what's harder to do with jj split than with git add --patch. Maybe an example would help?

(I understood the argument about jj split including all changes by default, but that changed when we started using scm-record by default.)

[chriskrycho]

@rmacklin I think there’s a conflation of things here: the specific UX of splitting in most diff editors is one thing; the workflow with jj split vs. git add --patch is another thing entirely. The thing I was raising originally here is the UX part. I would still really love it if my preferred diff editor had native support for the way jj split works, but I mostly use the included scm-diff-editor when I want to do something similar to git add --patch, and it works basically just like git add --patch does in practice, except, uhh, nicer? Net, I don’t miss the git add --patch workflow at all insofar as it involves an index rather than working with commits.

[ilyagr]

I would still really love it if my preferred diff editor had native support for the way jj split work

Does Kaleidoscope not have dir diff? I looked at their blog, and they have a promising post: https://blog.kaleidoscope.app/2024/04/16/folder-comparison-reinvented/ .

You are also welcome to submit a Kaleidoscope config either to the wiki or directly into jj's pre-configured tools. But man, $108/year is not cheap.

[chriskrycho]

@ilyagr they have dir diff, but it was broken at least until the most recent update (5.2) because they had historically not supported making changes in /tmp etc.

On the one hand, the price is steep in some ways; on the other hand, I want them to stay in business, and it is software I use literally every single day, many times a day. So I’ll take it!

[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.

[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.

[ilyagr]

(This is now fully implemented as the meld-3 diff editor; you can also try the similar diffedit3. See https://martinvonz.github.io/jj/latest/config/#experimental-3-pane-diff-editing)

[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 🤣 ))

[matklad]

I think I figured out how to get Magit-like UI for jj, without writing a jj-magit plugin for every editor:

https://matklad.github.io/2024/12/13/majjit-lsp.html

TL;DR:

• materialize Magit status text buffer as a real file on disk
• Use LSP to enrich it with jj functionality:
  • folding ranges to show diff for individual files/hunks
  • goto definition to jump from diff to "working copy"
  • code actions for "split off this hunk into a separate commit"

[WhyNotHugo]

Somewhat related here: the current UI is unusable with a keyboard. The typical shortcuts, Alt or Alt+f don't seem to open the menubar or file menu. These shortcuts have been the norm since at least the early nineties. I've no idea what they are in this case.

The ? keys shows a pop-up that reads:

You can click the menus with the mouse to view keyboard shortcuts.

I could get up and find my mouse somewhere downstairs (I eventually will), but requiring a mouse to see keyboard shortcuts is terrible usability and accessibility. Please keep in mind that some folks can't use a mouse, or have difficulty doing so, and those are the people who need to see keyboard shortcuts the most.

[martinvonz]

I think we all agree. I think it's simply that it's annoying until you've figured it out and then it's annoying anymore. So there's basically no incentive for people to fix it for themselves. We're just waiting for someone to do it only for others' benefit, or maybe because their employer tells them to.

[arxanas]

Tracking issue is here: arxanas/scm-record#44

[WhyNotHugo]

I didn't realise it was in a separate repository; I'll have a look.

Submitting contributions to jj requires signing up for a google account AND signing a CLA. I hope you can reconsider and accept contributions under the same licence as which this project is shared.

[martinvonz]

It's not my decision to make. It's Google's lawyers we need to convince. I think it will be hard, unfortunately.

[YaLTeR]

One more friction point for me: when splitting a complex change, I sometimes need to slightly edit the diff for the first commit so that it doesn't contain changes logically from the second commit. I usually find this out in the middle of a jj split -i, which means that I have to cancel it and redo the whole thing from scratch.

In vim-fugitive, as I'm staging hunks and lines, I can temporarily edit the file, stage that change, and undo it in the file to go into the second commit, all without interrupting or starting over the whole staging process. You can do the same in magit or any other git staging UI.

[talios]

The main pain point I have with jj split - when I have a large change, and I just want to split out a small portion - the default behavior is the new split has the existing change id, which I'd rather leave on the larger change (this may already be an option tho?)

[YaLTeR]

Oh yeah, this bites me whenever I describe a change first and then want to split out some smaller unrelated part. Then it gets the description instead of the rest of the change

[martinvonz]

Do you usually think of it in advance so a flag would help? Or would you need a command to swap two change ids after the split?

#1155 seems a bit related, btw.

[YaLTeR]

I think both could be useful.

[talios]

--before/--after mentioned in #1155 would suit my usage patten - but I agree with @YaLTeR that both could be useful.