From 6ebe9f8416887869a1ce3f9f3a529ccae4e8d87c Mon Sep 17 00:00:00 2001 From: Daniele Sassoli Date: Thu, 4 Sep 2025 09:55:13 +0100 Subject: [PATCH] docs: add working with gerrit section Currently there are instructions on how to setup jj to work with GitHub, but not Gerrit, which seems to be very popular with the jj community. Add a gerrit.md file to help users discover the jj gerrit subcommand. --- docs/gerrit.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + mkdocs.yml | 1 + 3 files changed, 112 insertions(+) create mode 100644 docs/gerrit.md diff --git a/docs/gerrit.md b/docs/gerrit.md new file mode 100644 index 0000000000..7edec28e6a --- /dev/null +++ b/docs/gerrit.md @@ -0,0 +1,110 @@ +# Using Jujutsu with Gerrit Code Review + +JJ and Gerrit share the same mental model, which makes Gerrit feel like a +natural collaboration tool for JJ. JJ tracks a "change identity" across +rewrites, and Gerrit’s `Change-Id` tracks the same logical change across patch +sets. JJ and Gerrit's `Change-Id`s aren’t natively compatible yet, but they’re +philosophically aligned. `jj gerrit upload` bridges the gap today by adding a +Gerrit-style `Change-Id` while JJ keeps its own notion of change identity on the +client. In practice, that means small, clean commits that evolve over +time, exactly how Gerrit wants you to work. + +This guide assumes a basic understanding of Git, Gerrit, and Jujutsu. + +## Set up a Gerrit remote + +Jujutsu communicates with Gerrit by pushing commits to a Git remote. If you're +starting from an existing Git repository with Gerrit remotes already configured, +you can use `jj git init --colocate` to start using JJ in that repo. Otherwise, +set up your Gerrit remote. + +```shell +# Option 1: Start JJ in an existing Git repo with Gerrit remotes +$ jj git init --colocate + +# Option 2: Add a Gerrit remote to a JJ repo +$ jj git remote add gerrit https://review.gerrithub.io/yourname/yourproject + +# Option 3: Clone the repo via jj +$ jj git clone https://review.gerrithub.io/your/project +``` + +If you used option 2 You can configure default values in your repository config +by appending the below to `.jj/repo/config.toml`, like so: + +```toml +[gerrit] +default-remote = "gerrit" # name of the Git remote to push to +default-remote-branch = "main" # target branch in Gerrit +``` + +## Basic workflow + +`jj gerrit upload` takes one or more revsets, and uploads the stack of commits +ending in them to Gerrit. Each JJ change will map to a single Gerrit change +based on the JJ change ID. This should be what you want most of the time, but if +you want to associate a JJ change with a specific change already uploaded to +Gerrit, you can copy the Change-Id footer from Gerrit to the bottom of the +commit description in JJ. + +> Note: Gerrit identifies and updates changes by the `Change-Id` trailer. When +> you re-upload a commit with the same `Change-Id`, Gerrit creates a new patch +> set. + +### Upload a single change + +```shell +# upload the previous commit (@-) for review to main +$ jj gerrit upload -r @- +``` + +## Selecting revisions (revsets) + +`jj gerrit upload` accepts one or more `-r/--revisions` arguments. Each argument +may expand to multiple commits. Common patterns: + +- `-r @-`: the commit previous to the one you're currently working on +- `-r A..B`: commits that are ancestors of B but not of A + +See the [revsets](revsets.md) guide for more information. + +### Preview without pushing + +Use `--dry-run` to see which commits would be modified and pushed, and where, +without changing anything or contacting the remote. + +```shell +$ jj gerrit upload -r '@-' --for main --dry-run +``` + +## Target branch and remote selection + +There are a few way of specifying the target remote for your projects: + +- Please run `jj config set --user gerrit.default-remote-branch ` to set your + default branch across all repos +- Please run `jj config set --repo gerrit.default-remote-branch ` to set your + default branch for this specific repo. +- Use `--remote-branch ` to override this for one specific occasion. + +The remote used to push is determined as follows: + +- If you have more than one origin, or the origin isn't called gerrit, run + `jj config set --repo gerrit.default_remote ` to set-up a + default remote. +- To upload to a specific remote as a one-off thing, use `--remote ` + +## Updating changes after review + +To address review feedback, update your revisions, then run `jj gerrit +upload` again with the same revsets. Gerrit will add new patch sets to the +existing changes instead of creating new ones. + +Examples: + +```shell +# Edit an earlier commit in the stack +$ jj edit xcv # position on the stack to edit + --- Apply needed edits --- +$ jj gerrit upload -r xcv +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 847643df1c..fef8a558d2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,6 +26,7 @@ You may want to jump to: - Overview of `jj` in the repo's [README](https://github.com/jj-vcs/jj?tab=readme-ov-file#readme) - [Installation and setup](install-and-setup.md) - [Tutorial and bird's eye view](tutorial.md) +- [Working with Gerrit](gerrit.md) - [Working with GitHub](github.md) - [Development roadmap](roadmap.md) - [Changelog](changelog.md) diff --git a/mkdocs.yml b/mkdocs.yml index c6c5e72108..befc7cd3b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -115,6 +115,7 @@ nav: # This lists all the files that become part of the documentation - Getting started: - Installation and setup: 'install-and-setup.md' - Tutorial and bird's eye view: 'tutorial.md' + - 'Working with Gerrit': 'gerrit.md' - Working with GitHub: 'github.md' - Working on Windows: 'windows.md'