It's too easy to get stuck in a state where jj undo doesn't work

[jvns]

I ran into an issue where something bad happened and jj undo didn't help. For me a big part of the promise of jj is that I can use jj undo to recover from mistakes.

I was doing something very basic, using jj 0.45.1:

1. Edit a commit message with jj describe
2. Get distracted and forget I was editing it
3. Run jj squash in another tab

This put me in a divergent state that I couldn't use jj undo to get out of. This is pretty basic/beginner usage of jj and IMO it shouldn't put you in a position where you have to learn about the op log and jj op restore. I would have much preferred it if e.g. jj refused to let me run jj squash while I had the describe open.

I'm very far from having a full understanding of all the reasons jj can end up with divergent states, so I don't know what jj should do here. This made me feel scared of using jj and it makes it hard for me to recommend to others. I've stopped using jj for now but hope to come back and try again later because I'm excited about the project.

Here's a small repro and all the error messages I ran into. Also apologies if "ideas" is not the right place, I tried to find the best fit.

Steps to reproduce

Repo setup:

jj git init
jj commit -m'commit 1'
jj commit -m'commit 2'
jj commit -m'commit 3'

jj log output to show the change IDs:

$ jj log -T builtin_log_oneline
@  qxppysxy julia 2026-10-03 11:43:33 6f9d88b4 (empty) (no description set)
○  qzzxxwkz julia 2026-10-03 11:43:33 c85c5434 (empty) commit 3
○  mmxqnwzu julia 2026-10-03 11:43:33 bec5feb1 (empty) commit 2
○  ouyrmxlv julia 2026-10-03 11:43:33 93a8f30d (empty) commit 1
◆  zzzzzzzz root() 00000000

Now open another terminal so we can run jj commands in parallel.

• terminal 1: run jj describe mmxqnwzu. Leave editor open & don't save.
• terminal 2: touch file.txt
• terminal 2: jj squash --into ouyrmxlv
• terminal 1: Edit commit message & save

Terminal 1 output (from jj squash --into ouyrmxlv)

Rebased 2 descendant commits.
Working copy  (@) now at: ppsunylz a94eada8 (empty) (no description set)
Parent commit (@-)      : qzzxxwkz be3b12dc (empty) commit 3

Terminal 2 error (from jj describe mmxqnwzu):

Rebased 2 descendant commits.
Warning: Failed to update Git HEAD ref
Caused by: The reference "HEAD" should have content c85c543415bf4c9b296fe6ba10a130c9ca47e1d7, actual content was be3b12dccb2ccff6c4687f8512cba53b5ede6f0f
Internal error: Failed to check out commit 73324a242758ff1757b67aa5848e6c85e3292e80
Caused by: Concurrent checkout

Now try to fix it with jj undo. This fails::

$ jj undo
Concurrent modification detected, resolving automatically.
Rebased 3 descendant commits onto commits rewritten by other operation.
Error: Cannot undo a merge operation
Hint: Consider using `jj op restore` instead

Now jj log:

$ jj log -T builtin_log_oneline
@  ppsunylz julia 2026-10-03 11:44:22 a94eada8 (empty) (no description set)
○  qzzxxwkz/2 julia 2026-10-03 11:44:22 be3b12dc (divergent) (empty) commit 3
○  mmxqnwzu/2 julia 2026-10-03 11:44:22 2f0f5247 (divergent) (empty) commit 2
│ ○  qxppysxy julia 2026-10-03 11:46:13 92cc87f1 (empty) (no description set)
│ ○  qzzxxwkz/0 julia 2026-10-03 11:46:13 120baee5 (divergent) (empty) commit 3
│ ○  mmxqnwzu/0 julia 2026-10-03 11:46:13 54a3602c (divergent) (empty) commit 2 (changed)
├─╯
○  ouyrmxlv julia 2026-10-03 11:44:22 3fa84805 commit 1
◆  zzzzzzzz root() 00000000

And jj op log:

$ jj op log
@    fd0740096c28 bork@watermelon.local default@ 4 minutes ago, lasted 28 milliseconds
├─╮  reconcile divergent operations
│ │  args: jj undo
○ │  7bebc3c48f17 bork@watermelon.local default@ 6 minutes ago, lasted 29 milliseconds
│ │  squash commits into 93a8f30dd339a2d146270680d54f59a7c1a4ba3e
│ │  args: jj squash --into o
○ │  6611e4140344 bork@watermelon.local default@ 6 minutes ago, lasted 15 milliseconds
│ │  snapshot working copy
│ │  args: jj squash --into o
│ ○  dde35cbf38e9 bork@watermelon.local default@ 6 minutes ago, lasted 22 seconds
├─╯  describe commit bec5feb18219b5f2ea876bee460e3bdfd7be9e4b
│    args: jj describe m
○  f6a68e364df5 bork@watermelon.local default@ 7 minutes ago, lasted 19 milliseconds
│  commit f3ec65847a5154765f5ae99059a938fa983a2a72
│  args: jj commit '-mcommit 3'
○  52c76fc22caf bork@watermelon.local default@ 7 minutes ago, lasted 18 milliseconds
│  commit fc58dfb06a717d857cee7c47a220155335c9e367
│  args: jj commit '-mcommit 2'
○  c14b13dd6f65 bork@watermelon.local default@ 7 minutes ago, lasted 18 milliseconds
│  commit 3d19f90db653eaf60fcfa4dae02a5d884841d887
│  args: jj commit '-mcommit 1'
○  3423cd8eccae bork@watermelon.local 7 minutes ago, lasted 17 milliseconds
│  add workspace 'default'
○  000000000000 root()

on jj converge

I asked in the Discord and got some advice to run jj converge. This is what it outputs. I don't understand what this means and it feels much too complicated relative to what I was trying to do.

$ jj converge
Found 2 divergent change(s) in the specified revset:
- Change: qzzxxwkztkyy with 2 commits:
    qzzxxwkz/0 120baee5 (divergent) (empty) commit 3
    qzzxxwkz/2 be3b12dc (divergent) (empty) commit 3

- Change: mmxqnwzulvrl with 2 commits:
    mmxqnwzu/0 54a3602c (divergent) (empty) commit 2 (changed)
    mmxqnwzu/2 2f0f5247 (divergent) (empty) commit 2

Choose which change to converge (jj converge only converges one change at a time):
1: qzzxxwkztkyy
2: mmxqnwzulvrl
q: abort

[jennings]

I wonder if jj undo should interactively ask which operation branch to travel down if stdout is a TTY. Something like:

The previous operation reconciled two divergent operations. Which one do you want to restore to?

1. 7bebc3c48f17 bork@watermelon.local default@ 6 minutes ago, lasted 29 milliseconds
   squash commits into 93a8f30dd339a2d146270680d54f59a7c1a4ba3e
   args: jj squash --into 
2. dde35cbf38e9 bork@watermelon.local default@ 6 minutes ago, lasted 22 seconds
   describe commit bec5feb18219b5f2ea876bee460e3bdfd7be9e4b
   args: jj describe m

(The text could be more explanatory)

[josephlou5]

What did you expect / want to happen? You did a jj describe on a commit that you squashed, so it failed when you tried to complete it because the commit no longer existed. I think the right course of action would have been to abort the describe command; you can do this in your editor or by ctrl-c or killing the jj describe process.

Also, I'm not sure the suggestion to have jj squash fail because a separate jj describe hasn't finished is a good idea. This means jj needs to keep track of external state, which does not really go well with the rest of the CLI IMO. It also makes things more complicated, both from a technical perspective and a UX perspective. And it's not exactly clear what criteria should be used to block other commands. For example should jj squash --interactive also block jj describe?

If you foresee yourself doing this a lot (I know someone who does), a solution I've heard of is to alias jj to a script that holds on to a global repo lock. This prevents any sort of concurrent modification. However I wouldn't really recommend this, as I imagine it wouldn't play well with things like editor integrations or separate terminals (or at least be annoying to work with).

[kamalmarhubi]

I worked with @jvns on writing this up. It's a situation I find myself in sometimes when doing a re-describe pass to tidy up the commit descriptions, and it's pretty annoying.

Re

You did a jj describe on a commit that you squashed, so it failed when you tried to complete it because the commit no longer existed.

This is not the case: in the example above, the describe was against the change mmxqnwzu, which was not squashed and remains in both of the divergent histories. The squash of qxppysxy into ouyrmxlv did cause mmxqnwzu to be rewritten as a descendant, and those concurrent operations resulted in the non-linear op log and the divergence.

This is visible in the final log showing the divergent changes, and in the op log showing the concurrent / divergent operations and their automatic reconciliation.

---

As for what could happen, there are at least a few options that would really help usability IMO. I don't have stats on how often different sources of divergence occur, but the long-running describe is probably pretty high on the list.

Some ideas we came up with that are more user-friendly:

• instead of leaving a second operation head which gets resolved into the non-working jj undo state, jj describe could have one of these behaviours:
  • prompt you on editor exit saying what happened below you, and ask if you want to (1) apply the describe to the revision despite said changes; (2) re-edit the description; (3) save the description you just wrote to a file and inspect, possibly including a jj describe incantation to apply the description from the file
  • varying increasingly do-what-I-mean versions of this, eg automatically apply the describe as a leaf operation if the description wasn't changed by the intervening operations and the revision is patch-id equivalent to its rewritten version
• default to a sort of "single-player mode" where jj would fail the squash operation because of the pending describe
  • I've still not dug into the transactions / operations / views model enough to know if this is viable
  • also gets into weird situations if we were modifying the earlier commit via working copy snapshots instead of jj squash?
    • I think it might be too different from how jj works today, though personally I think I'd prefer deferring working copy snapshots with a warning to the current behaviour, with a flag to force the snapshot

I'm pretty sure there are other things in the design space that would make it harder to get into a state where jj undo bails. And I think it's worth doing some "unprincipled" things in the CLI to help users, such as special casing how jj describe responds to this situation.

[PhilipMetzger]

And I think it's worth doing some "unprincipled" things in the CLI to help users, such as special casing how jj describe responds to this situation.

I disagree heavily with that. We should not special case anything since this makes it easier to reason about jj.

[josephlou5]

This is not the case: in the example above, the describe was against the change mmxqnwzu, which was not squashed and remains in both of the divergent histories.

Oops, missed that, thanks.

I don't have stats on how often different sources of divergence occur, but the long-running describe is probably pretty high on the list.

I mean, if you don't have stats, how do you know this is one of the most common? :) Personally I've only heard of "leaving describe open too long" from one other person (outside of this post). Rebasing commits in other workspaces as the cause of divergence is far more common IME. Of course if this is your top contender, that's totally fair.

• ...(3) save the description you just wrote to a file and inspect...

This would be nice for usability and for not losing work. I think there's usually a message if a describe fails about the temp file not being deleted though? Does that not happen in this case?

• varying increasingly do-what-I-mean versions of this, eg automatically apply the describe as a leaf operation if the description wasn't changed by the intervening operations and the revision is patch-id equivalent to its rewritten version

I feel like I remember someone suggesting something like this before. I could imagine some sort of automatic walk of "here's the commit ID I expected... here's the associated change ID... the description hasn't changed... apply to its latest commit ID". Not sure if it would be easy to do or work in all situations, but I would not mind that behavior tbh. Also note that jj currently does not have "patch-equivalent" semantics (#5381 I think).

default to a sort of "single-player mode" where jj would fail the squash operation because of the pending describe

Please see my other answer #10311 (comment). Tracking this external state is too complicated IMO.

[josephlou5]

This may also be a workflow thing. If you were super careful about finishing descriptions before doing other things, arguably you would not run into this. Or if you foresee many repo changes occurring while working on the description, you could edit it separately from jj entirely, then run the final jj describe at the end.

I recognize that this is not a pleasant situation to be in, but there are also ways to avoid it is what I'm trying to say.

[martinvonz]

Does the new jj converge command help?

[kamalmarhubi]

@martinvonz not really, as mentioned in the top post. The output was

$ jj converge
Found 2 divergent change(s) in the specified revset:
- Change: qzzxxwkztkyy with 2 commits:
    qzzxxwkz/0 120baee5 (divergent) (empty) commit 3
    qzzxxwkz/2 be3b12dc (divergent) (empty) commit 3

- Change: mmxqnwzulvrl with 2 commits:
    mmxqnwzu/0 54a3602c (divergent) (empty) commit 2 (changed)
    mmxqnwzu/2 2f0f5247 (divergent) (empty) commit 2

Choose which change to converge (jj converge only converges one change at a time):
1: qzzxxwkztkyy
2: mmxqnwzulvrl
q: abort

This is definitely better than just being told to learn the op log, but it's still a lot of new concepts to learn relative to how easy it is to get yourself into this state. And even if you know those concepts, it'd be nice to just have jj help you avoid this situation!

[PhilipMetzger]

I suggested converge in the Discord question.

[martinvonz]

FWIW, I would not mind if we had an opt-out (?) lock held by basically all commands. I think it's important that we don't need locks for correctness (no data loss without the locks), but I don't mind adding this kind of advisory locks for better UX.

[jvns]

I like that, I think that would have really helped here! It reminds me (in a good way) of how Git has a lock on the index file to stop you from doing certain kinds of operations in parallel.

[martinvonz]

Pretty sure Git's index lock is needed for correctness, though.

[martinvonz]

One thing to decide is whether we want such a lock to be held across several transactions/operations performed by a single command. For example, once #10301 lands, a single jj git push command can result in all these operations in series:

1. import git head
2. snapshot working copy
3. import git refs
4. sign commits
5. push to remote

We already hold a lock across the first 3 operations. The lock we're talking about adding here would have to span all the operations to prevent the repo changing while jj describe is editing the description. Note that it will make even things like jj log (without --ignore-working-copy or --no-integrate-operation) hang until they can acquire the lock (i.e. until you finish editing the description).

[josephlou5]

Yes, I think it should be across each singular command, so essentially the same as a jj shell wrapper that does the global lock itself. I'm not quite clear on whether this should be a repo lock or a workspace lock though; a repo lock wouldn't necessarily prevent workspace-related divergence (e.g., rebasing all).

The latency on other commands is also a concern for me. For example it would affect editor integrations or interactive tools like TUIs that are subprocessing to the CLI. It would almost be unusable from multiple surfaces it seems. So I think it's very important that this is an opt-in behavior, with appropriate caveats.

[yuja]

Another axis of command-level locking behavior is something like --no-integrate-operation-if-locked.

1. A background snapshot (or fetch) process starts without acquiring a lock.
2. A locked user process starts.
3. The background snapshot process attempts to acquire the lock before committing the transaction, and aborts.
4. The user process commits the transaction.