Jujutsu - My workflow – iamgianluca

Jujutsu - My workflow

Jujutsu is a relatively new version control tool that is very ergonomic and flexible. The main challenge I found is that both the official documentation and tutorials are very confusing regarding the recommended workflow.

In this brief post, I will show you the workflow I use. I hope this can be useful to you in getting started with jj.

# Initialize a new jj repository that shares storage with git
# --colocate means jj and git will work on the same repository
$ jj git init --colocate

# Set up a local bookmark to track the remote main branch
# This creates a local "main" bookmark that follows "main@origin"
$ jj bookmark track main@origin

To sync your local repo with the remote, and rebase:

# Fetch the latest changes from all remote repositories
# Updates remote-tracking bookmarks like main@origin
$ jj git fetch

# Rebase current commit and its ancestors onto the main bookmark
# This moves your work on top of the latest main branch
$ jj rebase -d main

Start working on a new feature branching off from the main bookmark/branch.

# Create a new commit on top of main bookmark with a descriptive message
# The new commit becomes your current working commit (@)
$ jj new main -m "implement features x and y"

# Make all your changes in this one commit

# Create a new bookmark called "feature-branch" pointing to current commit
# -r @ means "at revision @" (the current commit)
$ jj bookmark create feature-branch -r @

# Push the feature-branch bookmark and its commits to the remote repository
# This creates the branch on the remote for pull request creation
$ jj git push --bookmark feature-branch

The above will create a new branch in your GitHub repository. You can use that to create a Pull Request.

Alternatively, at times you need to work on a large feature, which you might want to break down into smaller changes that you can roll back if needed. Here’s how you can do that:

# Create a new working commit on top of main bookmark
$ jj new main

# Make some changes

# Create a new commit with the changes and move to it
$ jj new -m "add feature x"

# Implement feature x

# Create another new commit for the next feature
$ jj new -m "add feature y"

# Implement feature y

# Squash all commits after main into the current commit (@)
# This combines "add feature x" and "add feature y" into one commit
$ jj squash --from main..@

# Create a bookmark called "feature-branch" pointing to current commit
$ jj bookmark create feature-branch -r @

# Push the feature-branch bookmark to the remote repository
$ jj git push --bookmark feature-branch

Finally, if you’re working on a personal repository where you have direct push access to main, you can skip the pull request workflow entirely:

# Rebase your feature branch onto main
$ jj rebase -d main -s feature-branch

# Move main bookmark to include your changes
$ jj bookmark set main -r feature-branch

# Push to remote
$ jj git push --bookmark main

jj is quite flexible and accommodates different workflows (see here and here). The above are just the ones that works best for me right now.

You can learn about the other commands using jj --help.

Like with git, to fully master the tool, you should become intimately familiar with its commands and core concepts. There are several good resources for that. Here are a few I liked: