From f8e30fb1dec1e4b9bbb065af8dab8cd36db826db Mon Sep 17 00:00:00 2001 From: Martin von Zweigbergk Date: Tue, 1 Oct 2024 03:50:57 -0700 Subject: [PATCH] bookmarks: update docs to try to clarify mapping to Git branches I also removed a few instances suggesting that we might map bookmarks to something else in Git in the future (I don't think we have any such plans). --- docs/bookmarks.md | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/bookmarks.md b/docs/bookmarks.md index 59472120cc..7b2581eb53 100644 --- a/docs/bookmarks.md +++ b/docs/bookmarks.md @@ -3,17 +3,23 @@ ## Introduction -Bookmarks are named pointers to revisions (just like branches are in Git). You +Bookmarks are named pointers to revisions (just like branches are in Git). You can move them without affecting the target revision's identity. Bookmarks automatically move when revisions are rewritten (e.g. by `jj rebase`). You can pass a bookmark's name to commands that want a revision as argument. For example, -`jj new main` will create a new revision on top of the "main" bookmark. Use -`jj bookmark list` to list bookmarks and `jj bookmark` to create, move, or delete -bookmarks. There is currently no concept of an active/current/checked-out bookmark. +`jj new main` will create a new revision on top of the `main` bookmark. Use +`jj bookmark list` to list bookmarks and `jj bookmark ` to create, +move, or delete bookmarks. There is currently no concept of an +active/current/checked-out bookmark. -Currently Jujutsu maps its Bookmarks to Git Branches and stores them as that -in the Git backend. This means that all Bookmarks will be reflected as -Git Branches, this may change in the future. +## Mapping to Git branches + +Jujutsu maps its bookmarks to Git branches when interacting with Git repos. For +example, `jj git push --bookmark foo` will push the state of the `foo` bookmark +to the `foo` branch on the Git remote. Similarly, if you create a `bar` branch +in the backing Git repo, then a subsequent `jj git import` will create a `bar` +bookmark (reminder: that import happens automatically in +[colocated repos][colocated-repos]). ## Remotes and tracked bookmarks @@ -23,16 +29,17 @@ and `jj git push` of the bookmark. You can refer to the remembered remote bookma positions with `@`, such as `jj new main@origin`. `jj` does not provide a way to manually edit these recorded positions. -A remote bookmark can be associated with a local bookmark of the same name. This is -called a **tracked remote bookmark**, which currently maps to a Git remote -branch. When you pull a tracked bookmark from a remote, any changes compared to -the current record of the remote's state will be propagated to the corresponding -local bookmark, which will be created if it doesn't exist already. +A remote bookmark can be associated with a local bookmark of the same name. This +is called a **tracked remote bookmark** (which maps to a Git remote branch when +using the Git backend). When you pull a tracked bookmark from a remote, any +changes compared to the current record of the remote's state will be propagated +to the corresponding local bookmark, which will be created if it doesn't exist +already. !!! note "Details: how `fetch` pulls bookmarks" Let's say you run `jj git fetch --remote origin` and, during the fetch, `jj` - determines that the remote's "main" bookmark has been moved so that its target is + determines that the remote's `main` bookmark has been moved so that its target is now ahead of the local record in `main@origin`. `jj` will then update `main@origin` to the new target. If `main@origin` is @@ -227,4 +234,5 @@ command itself through an alias (as `jj b`), and for its subcommands. For example, `jj bookmark create BOOKMARK-NAME` can be abbreviated as `jj b c BOOKMARK-NAME`. +[colocated-repos]: git-compatibility.md#co-located-jujutsugit-repos [design]: design/tracking-branches.md