everything: Rename branches to bookmarks

[PhilipMetzger]

Jujutsu's branches do not behave like Git branches, which is a major hurdle for people adopting it from Git. They rather behave like Mercurial's (hg) bookmarks.

We've had multiple discussions about it in the last ~1.5 years about this rename in the Discord, where multiple people agreed that this false familiarity does not help anyone. Initially we were reluctant to do it but overtime, more and more users agreed that bookmark was a better for name the current mechanism. This may be hard break for current jj branch users, but it will immensly help Jujutsu's future, by defining it as our first own term. The [experimental-moving-branches] config option is currently left alone, to force not another large config update for users, since the last time this happened was when jj log -T show was removed, which immediately resulted in breaking users and introduced soft deprecations.

This name change will also make it easier to introduce Topics (#3402) as topological branches with a easier model.

This is a pure mechanical change done via LSP, ripgrep and sed with some manual fixups.

cc @thoughtpolice for help writing the deprecation text in the CHANGELOG.

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, demos/)
• I have updated the config schema (cli/src/config-schema.json)

[martinvonz]

I think we need to keep jj branch as an alias for a while. Same with the branches() revset and the various templates. Otherwise we're going to break too many tools and user configs.

[PhilipMetzger]

Yes, I'll need to partially revert those changes.

[joyously]

Do the bookmarks actually differ from tags?

[istudyatuni]

Do the bookmarks actually differ from tags?

You can't move tags

[PhilipMetzger]

Do the bookmarks actually differ from tags?

Which tags are you talking about, as tags could mean Git tags which we partially support or a tag of our own? Mercurial bookmarks and our branches behave similar to Git tags, except when the [experimental-advance-branches] config is set.

[martinvonz]

To clarify, the main difference between bookmarks and tags is that bookmarks move when you rewrite a commit. So if you run jj describe -m "new description" my-bookmark, then the bookmark is going to be updated to point to the rewritten commit. That only applies to the local side of the bookmark, however - the command will not move my-bookmark@origin, since that is supposed to represent the state seen on the remote.

[joyously]

From a high level viewpoint, it seems like bookmark would not cause a change in the display of the graph, but a branch would. So if you rename the concept of branch to bookmark, the creation of a bookmark would leave the graph in a straight line.

[arxanas]

@joyously Just to be clear, do you mean "lightweight tags" (refs) or "annotated tags" (objects)? The former wouldn't change the graph structure, but the latter would. Branches/bookmarks in git/hg/jj are refs, and I don't think jj has direct support for objects. Since jj doesn't currently move branches automatically, they essentially function like tags, except for interop purposes.

If I understand your viewpoint, you're saying that "branches" sound like objects in the commit graph, so "bookmarks" are a better term for that concept?

[martinvonz]

Since jj doesn't currently move branches automatically

Expect, importantly, when you rewrite the commit they point to. (We also move branches when we propagate changes from remotes and when you abandon a commit)

[joyously]

@arxanas Since I've never seen much about tags in jj (or in Git actually) , I don't know what they are. From a user standpoint, tags look like a label on a state which is denoted by a commit hash. But that sounds the same as a branch or a bookmark to me. Having to distinguish between them by whether they move or not is not the best. I can move a bookmark in my book. I can move a tag that I put on any object. Branches in physical trees don't move (all the growth is at the tip).

If I understand your viewpoint, you're saying that "branches" sound like objects in the commit graph, so "bookmarks" are a better term for that concept?

No, I didn't say that. I was trying to make sure that the graph wasn't affected. I've just read jj help branch and what it describes does sound more like bookmarks, although it seems like delete would delete your work.
Do you plan to have a different sort of branch in the future?

[necauqua]

Both git (lightweight) tags and branches are refs - pointers to a commit, "labels" if you will.

The distinction between tags and branches bookmarks in jj is that the local bookmark gets moved to the rewritten commit once you rewrite a bookmarked commit, and the tag stays - and they get exported as git branches/tags respectively.

So semantically, tags are named commit-ids, and bookmarks are named change-ids.

Of course, you could forcibly (re)move both of those with crud commands if you so desire (in an ideal world, as currently there are no crud commands for tags, we just read them from git)

And the future topics are named infectious (expand automatically when you create child commits, for the analogue of advancing branches) sets of commits, and not sets as in revsets, but actual real commits - and hopefully are to be the main tool for working with "branches" (but not like in git since we minimize global state, and topics are incredibly more versatile) in jj.

[joyously]

@necauqua Thank you. Perhaps you should put that writeup in the intro doc. Include the commands to create/delete a branch in the graph while you are at it, for completeness.

[martinvonz]

Just a partial review for now

[yuja]

While I like this PR, I cannot be confident that I've reviewed these changes thoroughly. It'll be nice if we can split this into smaller commits (something like UI changes + minimal test updates, other test changes such as renaming "branch1" to "bookmark1", internal API renames, ..), but I guess doing that would be tedious.

[ilyagr]

I got through a bit of the new bookmarks.md.

A couple of my suggestions definitely need fixing.

The rest are dependent on the questions of how we'd like our terminology of branches on the Git remote to work. For me, the most natural option would be to talk about branches on the Git remote, local bookmarks, and (most controversially) remote-tracking bookmarks. We could later split this file and talk about different kinds of remotes (once we support remotes other than Git remotes).

So, I suggested a few edits that maybe should not be acted upon until people agree how we want to speak of this. I didn't do those for the entire file, just a few to give people a taste of one option.

[PhilipMetzger]

The rest are dependent on the questions of how we'd like our terminology of branches on the Git remote to work. For me, the most natural option would be to talk about branches on the Git remote, local bookmarks, and (most controversially) remote-tracking bookmarks. We could later split this file and talk about different kinds of remotes (once we support remotes other than Git remotes).

I'd like to have "natural" option, but the whole bookmarks.md rework should be a follow-up. Since this already is dragging along for some time.

[martinvonz]

This is a pure mechanical change done via LSP, ripgrep and sed with some manual fixups.

I think this is obsolete, right?

[martinvonz]

I think it's just as easy for any reviewers to send followup PRs to fix anything they find as it is to comment on this PR, so I think it makes sense to just merge this as is.

[dbarnett]

🚀

Looked like way more of a process getting this merged than I would have expected. Thanks!