jj-git-workflow-conversion.md

Switching to Jujutsu workflows

When coming to Jujutsu, one may try to emulate their Git workflows directly. This is possible, but can cause a lot of difficulty.

This guide shows how to translate Git workflows to Jujutsu.

Getting started

Cloning an existing repository

To clone an existing Git repository

$ jj git clone git@github.com:martinvonz/jj.git --colocate

Converting a Git repository to Jujutsu

If you already have a Git repository, you can upgrade it to Jujutsu:

$ jj git init --git-repo my-repo

Starting a new line of work

Most people using Git are familiar with the pull request workflow:

• Create a new branch, commit work to that branch, and push
• Create a pull request where others review your work
• Add new commits to the branch to address feedback
• Eventually, merge the branch into the main branch (assumed to be "main")

With Git, that looks like this:

# Create and check out a new branch
$ git switch -c cool-feature

Starting a new line of work in Jujutsu looks like this:

$ jj new main

This creates a new, empty commit with the "main" branch as its parent. No branch name is required because Jujutsu keeps changes visible even without branches.

!!! info inline end "Branches are not used until you need to share your work"

Git requires all commits to either be pointed to by a branch, or to be the
ancestor of such a commit. Otherwise, the commit is "dangling" and may be lost.

Jujutsu does not require this. Changes (commits) remain visible even if no
branch is created.

Only when you want to share your work do you need to create a branch.

Committing new work

To commit new work with Git, one must change files on disk, add the changes to the index ("staging area"), then commit the changes:

# Make changes to files, then commit that work
$ git add -A
$ git commit -m "add a cool new feature"

Jujutsu does not require an "add" step. After making changes to files, no jj add is necessary because Jujutsu automatically updates the working copy commit.

!!! info inline end "The working copy commit is automatically updated"

After

Instead, you can simply add a commit message to the working copy commit:

$ jj describe -m "add a cool new feature"

Sharing your work with others

To share a Git branch, you push it to a remote repository, usually named "origin":

# Push the branch so a pull request can be opened
$ git push -u origin cool-feature

Jujutsu is similar. However, since you didn't create a branch when you started your work, you must create it now so you can push it:

$ jj branch create cool-feature
$ jj git push -b cool-feature

Addressing code review feedback by appending

When addressing feedback from code review, a pull request workflow encourages you to add new commits to your branch:

$ git add -A
$ git commit -m "address feedback"
$ git push

You can do the same with Jujutsu:

# Create a new, empty commit 
$ jj new cool-feature
$ jj describe -m "address feedback"

# Now make your changes - Jujutsu will automatically record them in the working
# copy commit

# Move the branch to the current commit and push
$ jj branch set cool-feature
$ jj git push -b cool-feature

Addressing code review feedback by editing commits

Because branches do not automatically move when using Jujutsu, adding new commits to an existing branch can be tedious.

Instead, Jujutsu encourages editing the commits instead of appending new ones.

Suppose you have the following changes in your branch:

$ jj log
@  klzomnqo jdoe@example.com 7 seconds ago 3501c99a
│  (empty) (no description set)
◉  ustlrxuw jdoe@example.com 1 day ago main 33f03358
│  Merged PR 4
│ ◉  kzmkqnly jdoe@example.com 1 minute ago cool-feature 246b29d8
├─╯  add a cool new feature
◉  tkvqyzwt jdoe@example.com 2 days ago 45eeda71
│  Merged PR 3
◉  uyozyrps jdoe@example.com 2 days ago d0da9daa
│  Merged PR 2

The branch cool-feature contains change kzmkqnly (Git commit ID 246b29d8). You can edit that change in-place:

# Make change kzmkqnly the working copy
$ jj edit kzmkqnly

# Edit files to address review feedback

# Push those changes
$ jj git push -b cool-feature

This will force-push to the branch "cool-feature".