Forem: Altariarite

A version control tutorial with jj: Submit and Perfect Your PR

Altariarite — Sat, 30 Aug 2025 20:43:09 +0000

In the first part of the series, we looked at how to set up a jj repo and make our first push to GitHub. We touched on "commit"s and bookmarks in jj. Be sure to check out that one if you don't know what these words mean!

Now we get into the more interesting stuff: how to submit PRs and edit them easily.

Note: I've since shortened the id for a jj commit to 4 characters in the config by setting 'format_short_id(id)' = 'id.shortest(4)' under template-aliases

0: Old friends, new friends, immutable friends

Before doing anything, let's run jj log again to check the status after our first push.

Hmm, something unusual is going on here. We said in the first tutorial that the line starting with ◆ is the root commit. Why is the root commit not shown here? Why is the ◆ on our previous commit? And what is this ~ thing?

Let's tackle these one by one. First of all, ~ means that there are more commits to be shown. We can see all the commits by running jj log -r 'all()'

◆ marks the root commit, but it also marks our "Add hello world" commit xvux that we just pushed to main. It means these are immutable commits. Indeed, if we try to edit it, we would get an error.

> jj edit x                                                                                                                                                                         (base)
Error: Commit 47b0d687d09c is immutable
Hint: Could not modify commit: xvux main | Add hello world
Hint: Immutable commits are used to protect shared history.
Hint: For more information, see:
      - https://jj-vcs.github.io/jj/latest/config/#set-of-immutable-commits
      - `jj help -k config`, "Set of immutable commits"
Hint: This operation would rewrite 1 immutable commits.

Since these commits cannot be modified, they are not very interesting to us. So jj hides them by default and only shows the latest immutable commit. I quite like that.

Note: technically the commit can be modified if you "force push" to main, but it is a very dangerous operation! We will not cover it here.

Now to the actual PR.

1: Create a Pull Request 🚀

Let's wrap our hello world in a function. We will make an intentional spelling error to be fixed later.

def hellp():
    print("hello world!")

Let's commit like before:

jj commit -m "my first pr"

We could create a new bookmark like we did before, but I am lazy and choose to let jj do it automatically this time.

jj git push --change t

jj will generate a bookmark on that commit and push. It will also generate a link for you to open a pull request.

Creating bookmark push-tsnxozwsqwwt for revision tsnxozwsqwwt
Changes to push to origin:
  Add bookmark <your-bookmark> to <some string>
remote:
remote: Create a pull request for <your-bookmark> on GitHub by visiting:
remote:      https://github.com/<your-repo>/pull/new/<your-bookmark>
remote:

2: Edit the PR with Feedback 🔄

Code review is a conversation and usually involves multiple back and forth edits. Let’s say a teammate reviews your PR and asks you to fix the typo.

With jj, there are ways to directly edit the original commit, which keeps the history clean.

Fixing the typo

After you write the fix, run jj diff. We see that saved changes are reflected.

Since the fix is happening in the "Working copy", it is now one commit ahead of our original commit. We want to move the fix down to our original commit.

jj squash will do exactly that. It takes our new change and move it down to the commit we pushed. Our bookmark will have a *, indicating that something changed in this commit.

> jj squash

Working copy  (@) now at: slzw (empty) (no description set)
Parent commit (@-)      : tsnx push-tsnxozwsqwwt* | my first pr

Running jj git push will push our fix to the branch and to the PR. This way you won't clutter the PR with commits like "Fix typo".

> jj git push

Changes to push to origin:
Move sideways bookmark push-tsnxozwsqwwt from 4bb496b59686 to 80c14a7f4239

Changing the commit message

Another teammate points out that your commit message and PR title shouldn't be named "my first pr" but something like "Refactor to hello()". That's a good point! The commit message is very easy to change in jj .

All we need is jj describe -r t -m "Refactor to hello()

Note: -r stands for "revision", a synonym to "commit". t is the shortest unique id for our commit

We can jj git push again.

And now the PR is ready to be merged!

This is the place where our local history will start to diverge from the remote repo. The remote repo might also change because other people are working on it at the same time as you. In the next tutorial, we will explore how to deal with the difference and sync from remote to local. Stay tuned!

A version control tutorial with jj: Commit and push your first change

Altariarite — Thu, 28 Aug 2025 23:35:05 +0000

jj is a shiny new version control system. I've been using it for a week now and it revolutionised my workflow with GitHub. It's simpler and more intuitive than git, but the official tutorial and the default UI can be a little daunting.

This guide will start with a simpler jj interface and walk you through common development workflows. We start from making a single change and go all the way to managing a stack of tiny pull requests.

I hope I can show you why jj feels amazing by the end! We'll use a simple Python project as our example.

Setup

First, let's set up our project and initialise it with jj .

1. Create your project:

mkdir jj-hello-world
cd jj-hello-world

2. Initialise jj and git:

jj works on top of a git repository, which allows it to integrate with platforms like GitHub.

jj git init

Note before we start: The default jj log shows a lot of stuff. That can be quite confusing for someone new to jj. When starting out I preferred to use a simpler interface. You can do that by writing some config to ~/.config/jj/config.toml

1. Your First Change

Now our journey starts! We start by running jj log.

Wow, what are all those things? 🤷‍♂️ A minute ago we just had an empty folder!

Turns out, every new jj repository starts with two "commits":

The line starting with ◆ is the root commit. It's the special, empty starting point of your project's entire history, identified by all Zs (zzzzzzzz). Think of it as the foundation upon which all your future work will be built.
The line starting with @ is your current working-copy commit. The @ symbol means this is your active workspace where any new file changes will be automatically tracked. In a brand new repository, this commit is also (empty) and has no description yet, ready for you to start coding.

Let's make a simple change.

1. Write a change:

Modify the main.py file and save.

print("hello world!")

jj automatically captures this change in your working copy. If we run jj log again, you will see that the (empty) tag is gone. jj knows that we have changed something.

We can see the change with jj diff

2. Commit your change:

jj commit -m "Add hello world"

Your jj log will now show three commits: the root commit, the feature you committed just now, and a new empty working-copy commit you're now on.

💡Note:
Your feature commit has the id xvuxvpsx. That's exactly the same as the id of the previous working copy. The new working copy has a new id that starts with m

3. Sync and first push:
Let's push your feature. Create a new, empty repository on GitHub. Then, add it as a remote.

# Replace <your-github-url> with your repository's URL
jj git remote add origin <your-github-url>

We want to give our commit a "bookmark". Since GitHub is organised around named branches, this bookmark tells jj which of your local commits should become a specific branch on the remote. We want to bookmark our feature commit as main.

jj bookmark create main -r x

💡Note:
-r stands for "revision", which is a synonym for "commit". And x is the shortest unique id for our local commit.

Push to remote.

jj git push --allow-new

Now your feature is on GitHub! \o/

Next up, we will look at creating and fixing PRs (pull requests), which happens all the time when you collaborate with someone on GitHub, or sometimes even when you work alone. Stay tuned!