diff --git a/docs/git-comparison.md b/docs/git-comparison.md
index 2d779317af..18895684da 100644
--- a/docs/git-comparison.md
+++ b/docs/git-comparison.md
@@ -22,19 +22,21 @@ various use cases.
to an intermediate commit between `HEAD` and the working copy, so workflows
that depend on it can be modeled using proper commits instead. Jujutsu has
excellent support for moving changes between commits. [Details](#the-index).
-* **No need for bookmark names (but they are supported).** Git lets you check out
- a commit without attaching a bookmark. It calls this state "detached HEAD". This
- is the normal state in Jujutsu (there's actually no way -- yet, at least -- to
- have an active bookmark). However, Jujutsu keeps track of all visible heads
+* **No need for branch names (but they are supported as
+ [bookmarks](glossary.md#bookmark)).** Git lets you check out a commit without
+ attaching a branch to it. It calls this state "detached HEAD". This is the
+ normal state in Jujutsu (there's actually no way -- yet, at least -- to have
+ an active branch/bookmark). However, Jujutsu keeps track of all visible heads
(leaves) of the commit graph, so the commits won't get lost or
garbage-collected.
-* **No current bookmark.** Git lets you check out a bookmark, making it the 'current
- bookmark', and new commits will automatically update the bookmark. This is
+* **No current branch.** Git lets you check out a branch, making it the 'current
+ branch', and new commits will automatically update the branch. This is
necessary in Git because Git might otherwise lose track of the new commits.
- Jujutsu does not have a 'current bookmark'; instead, you update bookmarks
- manually. For example, if you start work on top of a commit with a bookmark,
- new commits are created on top of the bookmark, then you issue a later command
- to update the bookmark.
+
+ Jujutsu does not have a corresponding concept of a 'current bookmark';
+ instead, you update bookmarks manually. For example, if you start work on top
+ of a commit with a bookmark, new commits are created on top of the bookmark,
+ then you issue a later command to update the bookmark.
* **Conflicts can be committed.** No commands fail because of merge conflicts.
The conflicts are instead recorded in commits and you can resolve them later.
[Details](conflicts.md).
@@ -43,11 +45,10 @@ various use cases.
automatically be rebased on top. Branches pointing to it will also get
updated, and so will the working copy if it points to any of the rebased
commits.
-* **Branches are identified by their names (across remotes).** For example, if
- you pull from a remote that has a `main` bookmark, you'll get a bookmark by that
- name in your local repo as well. If you then move it and push back to the
- remote, the `main` bookmark on the remote will be updated.
- [Details](bookmarks.md).
+* **Bookmarks/branches are identified by their names (across remotes).** For example, if
+ you pull from a remote that has a `main` branch, you'll get a bookmark by that
+ name in your local repo. If you then move it and push back to the remote, the
+ `main` branch on the remote will be updated. [Details](bookmarks.md).
* **The operation log replaces reflogs.** The operation log is similar to
reflogs, but is much more powerful. It keeps track of atomic updates to all
refs at once (Jujutsu thus improves on Git's per-ref history much in the same
@@ -56,7 +57,7 @@ various use cases.
* **There's a single, virtual root commit.** Like Mercurial, Jujutsu has a
virtual commit (with a hash consisting of only zeros) called the "root commit"
(called the "null revision" in Mercurial). This commit is a common ancestor of
- all commits. That removes the awkward state Git calls the "unborn bookmark"
+ all commits. That removes the awkward state Git calls the "unborn branch"
state (which is the state a newly initialized Git repo is in), and related
command-line flags (e.g. `git rebase --root`, `git checkout --orphan`).
@@ -107,16 +108,20 @@ parent.
| Clone an existing repo |
jj git clone <source> <destination> [--remote <remote name>] (there is no support
for cloning non-Git repos yet) |
- git clone <source> <destination> [--origin <remote name>] |
+ git clone <source> <destination&/gt; [--origin <remote name>] |
- | Update the local repo with all bookmarks from a remote |
+
+ Update the local repo with all bookmarks/branches from a remote |
jj git fetch [--remote <remote>] (there is no
support for fetching into non-Git repos yet) |
git fetch [<remote>] |
- | Update a remote repo with all bookmarks from the local repo |
+
+ Update a remote repo with all bookmarks/branches from the local repo |
jj git push --all [--remote <remote>] (there is no
support for pushing from non-Git repos yet) |
git push --all [<remote>] |
@@ -187,7 +192,7 @@ parent.
| See log of all reachable commits |
jj log -r 'all()' or jj log -r :: |
- git log --oneline --graph --decorate --bookmarks |
+ git log --oneline --graph --decorate --branches |
| Show log of commits not on the main bookmark |
@@ -243,17 +248,17 @@ parent.
git stash |
- | Start working on a new change based on the <main> bookmark |
+ Start working on a new change based on the <main> bookmark/branch |
jj new main |
git switch -c topic main or
git checkout -b topic main (may need to stash or commit
first) |
- | Move bookmark A onto bookmark B |
+ Move bookmark/branch A onto bookmark/branch B |
jj rebase -b A -d B |
git rebase B A
- (may need to rebase other descendant bookmarks separately) |
+ (may need to rebase other descendant branches separately)
| Move change A and its descendants onto change B |
@@ -324,29 +329,29 @@ parent.
git rev-parse --show-toplevel |
- | List bookmarks |
+ List bookmarks/branches |
jj bookmark list |
- git bookmark |
+ git branch |
- | Create a bookmark |
+ Create a bookmark/branch |
jj bookmark create <name> -r <revision> |
- git bookmark <name> <revision> |
+ git branch <name> <revision> |
- | Move a bookmark forward |
+ Move a bookmark/branch forward |
jj bookmark set <name> -r <revision> |
- git bookmark -f <name> <revision> |
+ git branch -f <name> <revision> |
- | Move a bookmark backward or sideways |
+ Move a bookmark/branch backward or sideways |
jj bookmark set <name> -r <revision> --allow-backwards |
- git bookmark -f <name> <revision> |
+ git branch -f <name> <revision> |
- | Delete a bookmark |
+ Delete a bookmark/branch |
jj bookmark delete <name> |
- git bookmark --delete <name> |
+ git branch --delete <name> |
| See log of operations performed on the repo |
diff --git a/docs/glossary.md b/docs/glossary.md
index 5b868e8290..b849dc02d5 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -2,11 +2,11 @@
## Anonymous branch
-An anonymous branch is a chain of commits that doesn't have any
-[named bookmarks](#bookmark) pointing to it or to any of its descendants. Unlike
-Git, Jujutsu keeps commits on anonymous branches around until they are
-explicitly abandoned. Visible anonymous branches are tracked by the
-[view](#view), which stores a list of [heads](#head) of such branches.
+An anonymous branch is a chain of commits that doesn't necessarily have any
+[bookmarks](#bookmark) pointing to it or to any of its descendants. Unlike Git,
+Jujutsu keeps commits on anonymous branches around until they are explicitly
+abandoned. Visible anonymous branches are tracked by the [view](#view), which
+stores a list of [heads](#head) of such branches.
## Backend
@@ -22,12 +22,24 @@ such as the "operation store backend" for storing
## Bookmark
-A bookmark is a named pointer to a [commit](#commit). They automatically follow
-the commit if it gets [rewritten](#rewrite). Bookmarks are sometimes called
-"named branches" to distinguish them from [anonymous branches](#anonymous-branch).
-They are similar to Git's branches and even more similar to
-[Mercurial's bookmarks](https://wiki.mercurial-scm.org/Bookmarks). See
-[here](bookmarks.md) for details.
+A bookmark is a named pointer to a [commit](#commit). They are similar to Git's
+[branches](#branch) and even more similar to [Mercurial's
+bookmarks](https://wiki.mercurial-scm.org/Bookmarks). See [here](bookmarks.md)
+for details.
+
+Unlike in Git, there is no concept of a "current bookmark"; bookmarks *do not*
+move when you create a new commit. Bookmarks *do* automatically follow the
+commit if it gets [rewritten](#rewrite).
+
+## Branch
+
+In the context of `jj`, the work "branch" usually refers to an [anonymous
+branch](#anonymous-branch) or, less formally, a branch of the commit "tree"
+(which is itself an informal way to refer to the commit graph).
+
+These docs also sometimes discuss Git's branches and branches on Git remotes.
+Locally, these correspond to [bookmarks](#bookmark). In a co-located repository,
+each local Git branch corresponds to a `jj` bookmark.
## Change