The Squash Workflow

Important

You learn a workflow that feels both exotic (committing before coding!) and familiar (it acts like the Git index).

This is apparently the preferred workflow of Martin von Zweigbergk, the creator of Jujutsu, so it must be deeply rooted in its philosophy.

In a nutshell:

• You start by committing .
• You code in a disposable Change on top of it.
• When done, you squash your work down.

Let me show you:

@  p        ▢
○  o        Play instructions **manual***
○  kx       Play manual
~

Let’s say you want to add the obligatory cat picture to your project manual.

First: Commit!

You start by declaring your intent:

jj new -r manual -m "Cat picture"

@  vt       ▢ Cat picture
○  o        Play instructions **manual***
○  kx       Play manual
~

You haven’t coded yet, so the Change is empty. It’s the candidate for the next commit, much like the Git index.

Second: Set Up Your Workspace

You build a disposable Change on top of your Candidate Change:

jj new

@  xq       ▢
○  vt       ▢ Cat picture
○  o        Play instructions **manual***
○  kx       Play manual
~

This empty, descriptionless Change mimics Git:

Third: You Code

Nothing new to see here: Jujutsu reflects every file system change in your Current Change @. Here comes the cat:

echo '![cat](https://upload.wikimedia.org/wikipedia/commons/5/58/Cat_Sima.jpeg)' >> manual.md

Finally: You Squash

The tip Change is populated, the Candidate Change is still empty. This give you the time to review your code. When you are happy, you squash your work back into the Candidate Change:

jj squash

If you want to squash interactively chunk by chunk, you can do:

jj squash -i

When jj squash completes, the empty tip Change is abandoned and replaced with a fresh one automatically.

@  zu       ▢
○  vt       Cat picture
○  o        Play instructions **manual***
○  kx       Play manual
~

Lather, rinse, repeat.

Your next step would be describing the Current Change with your next goal (jj desc -m DESCRIPTION) and building a working area on top of it (jj new). This workflow is so idiomatic that Jujutsu provides a shortcut for it: jj commit -m DESCRIPTION¹.

1. Does committing before coding feel weird? Think of it as the TDD equivalent for commits: you declare intent before doing, turning commit into an actual commitment. You can read more on this idea in Pre-emptive Commit Messages. ↩