Don’t Edit

Important

You conclude that the Git Index was a Good Thing®, and you learn a micro-workflow that builds on the same idea.

In Committing, I warned:

By editing the file system, you directly edit the commit. This is somewhat dangerous.

In hindsight, I was a bit dramatic. After all, Jujutsu, like Git, never deletes information, so there’s nothing really dangerous.
But why let accuracy spoil good drama? So, let me reformulate the idea as follows:

Directly performing open-heart surgery on a Change with jj edit is dramatically more perilous than working from a distance, on a new Change on top of it.

Terrified? Good. (Really, you have no reason to be, but good).

What’s Wrong With Editing?

jj edit is ruthless: it unconditionally commits every filesystem change. Even worse, editing a historical Change recursively propagates modifications to its descendants. The problem is, not all changes are intentional:

• Build tools create artifacts before you can add them to .gitignore.
• We all make fat-finger mistakes. “Mistakes” plus “automatic recursive propagation” is the recipe for disaster.
• Editors leave stray files behind.

Indeed, a universal rule for both Git and Jujutsu is:

Always review changes before committing them.

This is why the Git Index exists. jj edit is often too rushed.

The solution: whenever you’re tempted to jj edit X, use jj new X instead. Instead of performing surgery directly on X, jj new provides a safe, isolated working area.

Mini-workflow

To safely edit X:

1. Run jj new X.
2. Make your edits.
3. Review your work with jj diff, then squash it back with jj squash.
4. To start over, use jj restore.

See This In Practice

Using our sample repo, say you want to edit v:

○  zx       Click alternates Xs and Os **dev***
○  v        Click sets a X                    <-- What you want to edit
○  s        Square has state
~

Instead of jj edit v, use jj new v:

@  p        ▢                                 <-- Your Current 
│ ○  zx       Click alternates Xs and Os **dev***
├─╯
○  v        Click sets a X                    <-- What you want to 
○  s        Square has state

Notice you landed:

• On an empty, descriptionless Change.
• Sitting directly on top of the Change you want to edit.

Let me call that empty Change the Buffer Change. If you squint, you could think of it as a Git Index-like structure. Only, it’s an ordinary Change, so it’s persistent and operable with the ordinary commands.

Isn’t This Just jj edit?

Definitely no. If you ran jj edit v:

• jj diff would mash your edits together with v’s original changes, making review difficult.
• jj restore would wipe both your new changes and v’s original changes, resetting everything to s.

The Joy Of No Special Cases

Because the Buffer Change is an ordinary Change, you gain huge benefits.

There’s No Need for jj stash

Need to switch context immediately?

• In Git, you must git stash push or lose your work.
• In Jujutsu, just run jj new somewhere else. Your Buffer Change waits safely.

There’s no separate stash machinery. Suspended work lives as normal Changes. Remember when in Why I said that the Git index is like a commit, but not quite? If you think about it, the Git stash is another case of quasi-commit, requiring a special treatment.

Jujutsu turns the entire stash concept into basic primitives you already know.

Multiple Indexes

Have you ever thought you can have multiple indexes?
Say you want to try a different approach while editing v. You run another jj new v and, voilà!, you get two independent Buffer Changes. Work on both, abandon one, or squash both. Your choice.