jj-bookmark

Create a new bookmark at the given revision

$ jj [[b|bookmark]] [[c|create]] [[-r|--revision]] [revision] [name]

$ jj [[b|bookmark]] [[l|list]]

$ jj [[b|bookmark]] [[m|move]] [[-t|--to]] [revision] [name]

$ jj [[b|bookmark]] [[t|track]] [name]@[remote]

$ jj [[b|bookmark]] [[d|delete]] [name]

$ jj [[b|bookmark]] [[f|forget]] [name]

jj bookmark [OPTIONS] [<NAMES>...]

<NAMES>...
    One or more names of bookmarks to create, delete, or list. When creating, these are the names of the new bookmarks. When deleting, these are the names of bookmarks to remove. If no names are provided, a new bookmark is created at the current revision by default (unless --list is used).

--delete, -d
    Deletes the specified bookmarks. Requires bookmark names to be provided as arguments.

--force, -f
    Allows creating a bookmark that already exists (it will be moved to the new revision), or deleting a bookmark that does not exist (the command will not error out). This option overrides normal safety checks.

--name <NAME>
    Explicitly specifies the name of the bookmark to operate on. This option can be used multiple times to specify multiple names, similar to the positional arguments.

--revision <REVISION>, -r <REVISION>
    Specifies the revision to which the bookmark should point. If omitted when creating a bookmark, the bookmark will point to the current working copy's revision.

--message <MESSAGE>, -m <MESSAGE>
    Attaches an optional message to the bookmark. While technically possible, this is less commonly used for bookmarks than for tags.

--list, -l
    Lists all existing bookmarks in the repository. When used, any other creation or deletion arguments are ignored, and the command simply displays the list of bookmarks.

--all
    Used in conjunction with --list, this option displays all bookmarks, including those in the working copy that might not be immediately visible in the current view or filtered out by default.

The jj bookmark command in the Jujutsu (jj) version control system allows users to create, delete, and list bookmarks. Bookmarks are lightweight, local pointers to specific revisions in the repository's history. Unlike branches, which are typically synchronized with remote repositories and represent shared lines of development, bookmarks are strictly local and are not automatically pushed or pulled. They serve as a convenient mechanism for marking revisions that a user might want to revisit quickly, for temporary work, or for internal navigation without the overhead of creating a full branch. By default, running jj bookmark creates a new bookmark pointing to the current revision. Users can specify a target revision, delete existing bookmarks, or list all active bookmarks. Their mutable nature makes them ideal for quickly marking and moving pointers as work progresses.

Jujutsu bookmarks are strictly local to your repository and are not designed for synchronization with remote repositories. They are mutable and can be easily moved or deleted, making them less suitable for marking immutable historical points (like releases) compared to 'tags'. They do not create new branches in the traditional Git sense and are purely for personal navigation and temporary markers.

In Jujutsu, the primary distinction between bookmarks and branches is their scope and synchronization behavior. Branches are intended for shared development, can be pushed and pulled to remotes, and typically represent named lines of development. Bookmarks, conversely, are purely local, are not synchronized, and serve as personal, temporary pointers that are easily moved or discarded. They are often used for quick navigation or marking revisions during a feature's development cycle.

While both bookmarks and tags point to specific revisions, their intended use differs. Bookmarks are mutable and designed to be moved or deleted frequently for personal workflow management. Tags, particularly Git tags (which Jujutsu can interact with), are generally considered immutable and are used for marking significant, permanent points in history, such as release versions. Jujutsu's native tags also share this immutability characteristic when used, though they are less frequently used than Git tags due to Jujutsu's mutable history model.

The jj-bookmark command is an integral part of the Jujutsu (jj) version control system, which was developed by Martin Jambon. Jujutsu aims to offer a more intuitive and powerful alternative to Git, focusing on a mutable history model and a rebase-centric workflow. Bookmarks were introduced as a core feature to provide a lightweight, local mechanism for marking revisions, complementing jj branch for shared development and jj tag for immutable references. Its design reflects Jujutsu's philosophy of providing flexible tools for local repository manipulation and navigation.

jj branch(1), jj tag(1), jj log(1), jj commit(1), jj new(1)