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.

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

[redbaron]

@chriskrycho, did anything improved in Kaleidoscope && jj integration since then?

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

[kika]

The '?' dialog was fixed in the scm-record repo quite a long time ago
arxanas/scm-record#91

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

[salty-horse]

What I'm missing is a graphical tool like Git's built-in git gui, whose main purpose is to select hunks, and generate new commits out of them, or amend the last commit.

With jj, that would mean being able to point at any commit, "stage" hunks, select a target (either a new commit that's a parent of the current one, or a different one selected from a visual log tree), and be able to review how the final change looks before confirmation, before repeating the process with more hunks.

One confusion I had with split: After selecting the lines in diff editor, it asks to "Enter a description for the first commit", without any preview of the selected changes (a file list is not enough when changing a single file), so I was unsure whether it referred to the new commit that was being created, or the one that was being broken apart. Perhaps "new" is a better description than "first"?

Is there way to get jj describe to include a complete diff in the text editor?

[cenviity]

One confusion I had with split: After selecting the lines in diff editor, it asks to "Enter a description for the first commit", without any preview of the selected changes (a file list is not enough when changing a single file), so I was unsure whether it referred to the new commit that was being created, or the one that was being broken apart. Perhaps "new" is a better description than "first"?

This will be addressed by #6509.

[aslatter]

What I've been experimenting with is a diff-tool which mimics the behavior of "git add -p" or the --patch flag from Git.

I took the approach of diffing "left" and "right", asking the user which changes to keep, and then applying the inverse of the not-selected changes to "right" to end up in the stat jj expects (I have to flip all of the "add" operations to "remove" operations etc).

This seems to result in a user-experience that makes sense to me, and seems to work in a reasonably intuitive way for split, squash, and restore.

[jennings]

Have you seen the “gitpatch” merge tool script that someone dreamed up? I use this regularly and it sounds like what you’re describing.

(I thought I had added this to the wiki but it’s not there, so I guess not.)

[PhilipMetzger]

@jakobhellermann came up with the "gitpatch" merge tool, FYI

[aslatter]

Oh beautiful. That's way less jank than the diff-tool I had.

[vlovich]

Just wanted to add that I have the exact same problem. I personally find git gui is the best experiencing for splitting a commit - I can select hunks or visually select lines or select a hunk and visually deselect a line. It's the most efficient flow for splitting with Git & I wish something that simple existed for jj.

[TapGhoul]

In regards to when invoked via --tool, one friction point I want to add - the JJ-INSTRUCTIONS file when using tool is fairly confusing.
The current text reads as:

You are splitting a commit into two: oxorpwqq 16ec687f Description of what I want to split

The diff initially shows the changes in the commit you're splitting.

Adjust the right side until it shows the contents you want to split into the
new commit.
The changes that are not selected will replace the original commit.

I find this very confusing, as what I expect to happen based on this and what actually happens seems backwards.
The problem is that I expect the "original" commit to be the parent, and the "new commit" to be the child - but the relationship here is reversed.

All contents on the right side of the left/right split become the contents of the new parent - what I expect to be "original" - and anything removed becomes the contents of the new child - what I expect to be the "new" commit.

The diagrams somewhat help, in that it shows "remaining" is the stuff that's left - but I still find this initially confusing as "remaining" (without "selected") I expect to actually mean "What I did not remove"

The fact that the new automatically active commit is the "remaining" commit makes this text confusing too.
Maybe some text more like

You are splitting a commit into two: oxorpwqq 16ec687f Description of what I want to split

The left shows the parent commit, and the right is the original commit you wish to split.

Adjust the right side until it shows the contents to keep in your original commit.
The changes that are not retained will be moved to a new commit.

However, this is still confusing with --onto and the like, as the retained changes are not kept in the original change - the behaviour is reversed. When using no flags, the retained changes are kept in the original commit, with the original jj change ID. When there are flags, the retained changes are moved to the new jj change ID, and are stripped from the original one.

This makes understanding of the command's behaviour very confusing, I don't know how I'd be expected to intuit it. I kinda wonder if this divergence of behaviour is a bug? The diagrams in help explain it, but the behaviour still seems inconsistent and backwards, and the instructions generated are far too vague.

If not a bug, it might be worth having 2 separate sets of instructions depending on if you are splitting the change into 2 sequential commits, or are providing a target to split to.

[martinvonz]

Agreed. This is #9246.

[TapGhoul]

@martinvonz That issue addresses the instructions, but there's still the issue of divergent behaviour I mentioned at the end of the comment that also makes it rather unintuitive - if splitting without a target, retained changes are kept in the old commit. If splitting with a target, retained changes are moved to the new commit. It's a bit confusing there.

[martinvonz]

Makes sense. #6466 would make that consistent. Perhaps it's the right thing to do. My main concern with that PR is that it makes jj split; jj squash not preserve the change id. Perhaps that's fine.

Another option is to move the current jj split -o/-A/-B functionality into a new jj extract or similar.

[TapGhoul]

I kinda wonder if it might make more sense to make jj split with a target do what target-less does currently, and then describe it almost as a "lossless interactive restore" or something like that. Though that would betray its purpose a little, so I'm not sure - I think it's an issue of framing as to why it's difficult to find a happy medium right now. A separate command might work, but as is there's already the issue that jj diff and jj interdiff feel decoupled in a way that feels like they shouldn't be, at least to me - this would only compound that.

[MrAnno]

Many people mentioned that they miss the intuitive GUI experience that, for example, git gui provided.

It's probably a terrible idea, but would it be insane to support a jj split and jj commit flag that would take the current git index as the input for the split operation when git colocation is enabled? That way, everyone could use their favorite tool to split or interactively commit changes.

[ilyapoz]

This was discussed on discord and the proposal is to use a diff tool passed to jj split that would extract the git index and make it as if the same diff was chosen interactively.

I have not tried this yet.

https://discord.com/channels/968932220549103686/1499812978911088800/1502724136273711174

[ilyapoz]

https://gist.github.com/mystor/10111f7bc9fd14fea1301ce1b33b593d

[MrAnno]

@ilyapoz This is amazing. Thank you :)

Please consider adding export LC_ALL=C or anything similar to the script, as comm and sort may disagree otherwise:

comm: file 2 is not in sorted order
comm: input is not in sorted order
Error: Failed to edit diff

[ilyapoz]

this is not my script, I think you can comment in the gist