Moving Bookmarks

Did you notice the jj bookmark advance command? Mysterious, isn't it? It deserves a few words.

In fact, the only observation worth noting about local Bookmarks is about how and when Git and Jujutsu decide to move them on their own.

As a general rule, in Jujutsu Bookmarks stick to the Change they were created on. You can move entire trees of your history around and they'll move with it, rather then being left behind on old commits as in Git. In other words: Bookmarks stick to Changes, not to the underlying Git commits.

In Git you can get the same behavior with the --update-refs option of rebase ¹. In Jujutsu, it's the default.

Bookmarks Don't Follow Commits

In Git there's a notion of the current branch which follows your work as you make new commits.

There's nothing of the sort in Jujutsu: a Bookmark never changes the Change it points to, unless you explicitly ask it to. Not even when you make commits. Look. Here I'm using jj commit, which is equivalent to jj desc followed by jj new:

jj git init
jj bookmark create main
jj commit -m "Hello"

@  w    (empty)
○  k    (empty) main Hello
◆  z    (empty)

echo 'print("Hello, World!")' > main.py
jj squash

@  zl   (empty)
○  k    main Hello
◆  zz   (empty)

jj commit -m "Hola"
echo 'print("Hola, Mundo!")' >> main.py
jj squash

@  n    (empty)
○  o    Hola
○  k    main Hello
◆  z    (empty)

main stayed behind, stuck to k!

Git does the opposite, and it is easy to see why: after git commit, if the branch was not moved onto your new commit, you would be left in detached head, a condition that Git considers dangerous. Jujutsu has a different opinion on danger.

Manually Updating Bookmark Positions

But isn't updating Bookmarks by hand just an annoyance? Indeed, this often makes newcomers frown. I promise that over time it's easy to come to appreciate the elegance.

I like to see it this way: I love how Jujutsu keeps nudging me toward code reviews. If you think about it, Jujutsu's Stash Workflow revolves around the idea of getting a chance to run a jj diff before squashing the edits into a Change.
With Bookmarks it's not that different. The tree manipulation is so frequent and pervasive that it makes to review the history before publishing the result.

On top of that, what normally happens is even simpler: Bookmarks are created only at the very last moment, right before creating the Pull Request. The idiomatic way to use Jujutsu is as a branchless versioning system.

Bottom line: jj advance is the operation equivalent to what Git automatically does every time you git commit. Being manual, it gives you the time to review the history before a push.

This is all you need to know about Jujutsu's local Bookmarks. Things get more interesting when remotes come into play.

1. https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---update-refs ↩