docs: add working with gerrit section #7396

DanieleSassoli · 2025-09-01T09:58:34Z

This PR depends on @matts1 change that addst the Gerrit upload
command.

I should add, I'm very new to JJ and this is my first contribution.
Please let me know if I did anything wrong.

Checklist

If applicable:

[N/A] I have updated CHANGELOG.md
I have updated the documentation (README.md, docs/, demos/)
[N/A] I have updated the config schema (cli/src/config-schema.json)
[N/A] I have added/updated tests to cover my changes

PhilipMetzger · 2025-09-01T12:41:59Z

This in general looks good to me, but your patch is failing the CI because the commit title not the PR title should be docs: <your-title> so to fix it copy the current PR title to the commit description and re-push it again.

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.

matts1

Generally looks pretty good, but 3 main focus areas:

User guides should focus on how a user interacts with something, rather than the technical details of how it works under the hood
You make a lot of assumptions about the user's workflow, in particular @- vs @. JJ does not distinguish these. You're welcome to use @- in your examples, but we should avoid making assumptions and saying things like "@- is the last non-empty commit"
One thing it appears you've missed in how the command works is that when you push to gerrit, you are pushing not just a single commit, but a stack of changes. So your usage of trunk()..@- are equivalent to @-

matts1 · 2025-09-01T23:43:31Z

docs/gerrit.md

+
+```shell
+# Option 1: Start JJ in an existing Git repo with Gerrit remotes
+$ jj git init --colocate


Probably should be an option 3: jj git clone

matts1 · 2025-09-01T23:44:13Z

docs/gerrit.md

+```
+
+You can configure default values in your repository config by appending the
+below to `.jj/repo/config.toml`, like so:


Can we add a note that this is generally only useful for option 2

matts1 · 2025-09-01T23:51:18Z

docs/gerrit.md

+## Basic workflow
+
+`jj gerrit upload` takes one or more revsets, ensures each selected commit has a
+Gerrit-compatible `Change-Id:` footer (adding one if missing), and pushes the


This is phrased from a technical perspective of how it works, rather than from the perspective of a user. I suggest:
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.

matts1 · 2025-09-01T23:53:40Z

docs/gerrit.md

+### upload a single change
+
+```shell
+# upload the last real commit (@-) for review to main


I don't think we should call this the "last real commit". @ is a real commit too (in the sense that it has a commit object associated with it). Your interpretation of "last real commit" also assumes the squash workflow, rather than the edit workflow, both of which work just fine with jj gerrit upload.

matts1 · 2025-09-01T23:56:26Z

docs/gerrit.md

+See the [revsets](./revsets.md) guide for more.
+
+> Warning
+> The working-copy commit `@` is empty and is rejected. Use `@-` or another


This is making another assumption about workflows that isn't necessarily true for everyone. Empty commits are rejected. I usually upload @, and my @ is non-empty.

matts1 · 2025-09-02T00:05:18Z

docs/gerrit.md

+
+## Updating changes after review
+
+To address review feedback, amend or rewrite your commits, then run `jj gerrit


Nit: s/amend or rewrite your commits/update your revisions.

Amend is a bit of an overloaded term, and we work with revisions / changes in jj, not commits

matts1 · 2025-09-02T00:06:32Z

docs/gerrit.md

+## Updating changes after review
+
+To address review feedback, amend or rewrite your commits, then run `jj gerrit
+upload` again with the same revsets. Because the `Change-Id` footer is preserved,


Nit: this is a user guide, can we remove the "Because the change-ID footer is preserved". This is another one of those things that the user doesn't need to know. All they need to know is "I say upload, and it updates an existing gerrit change because I already uploaded it"

Change-Id is a trailer. I believe gerrit used to use the term footer, but it seems now git officially supports them, they're trailers, and JJ also uses the term trailer.

Since we've already mentioned the trailer earlier (well, see my previous comment) we could probably omit repeating it here?

matts1 · 2025-09-02T00:09:05Z

docs/gerrit.md

+## Target branch and remote selection
+
+You must specify the target branch for review with `--for <branch>` or by
+configuring `[gerrit].default_for`.


This is the technical details. From a user's perspective, they simply need to know:

Please run jj config set --user gerrit.default_for <branch name> to set your default branch across all repos

Please run jj config set --repo gerrit.default_for <branch name> to set your default branch for this specific repo.

Use --for <branch name> to override this for one specific occasion.

matts1 · 2025-09-02T00:11:23Z

docs/gerrit.md

+You must specify the target branch for review with `--for <branch>` or by
+configuring `[gerrit].default_for`.
+
+The remote used to push is determined as follows:


Again, more technical details. What the user needs to know

If your upload isn't going to gerrit, run jj config set --repo gerrit.default_remote <gerrit remote name>

To upload to a specific remote as a one-off thing, use --remote <remote name>

matts1 · 2025-09-02T00:11:41Z

docs/gerrit.md

+without changing anything or contacting the remote.
+
+```shell
+$ jj gerrit upload -r 'trunk()..@-' --for main --dry-run


As mentioned before, trunk()..@- isn't required

matts1 · 2025-09-02T05:03:57Z

I've updated the docstrings for the commands in the original pr, since the behaviour around stacked commits was very non-obvious.

talios · 2025-09-02T10:03:04Z

docs/gerrit.md

+resulting heads to `refs/for/<branch>` on your Gerrit remote.
+
+> Note
+> Gerrit identifies and updates changes by `Change-Id`. When you reupload a


Is it worth being explicit and mentioning that Change-Id is a commit trailer?

PhilipMetzger

just minor stuff

PhilipMetzger · 2025-09-02T11:49:50Z

docs/gerrit.md

+- `-r 'trunk()..@-'`: everything on top of trunk
+- `-r 'A..B'`: commits reachable from `B` but not `A`
+
+See the [revsets](./revsets.md) guide for more.


nit: remove ./ as we generally use relative links

PhilipMetzger · 2025-09-02T11:51:39Z

docs/gerrit.md

+$ jj gerrit upload -r 'xcv'
+```
+
+## Future: native Jujutsu metadata in Gerrit


I agree with Matt since we already have a familiar wording in the FAQ. The thing Daniel could do is link out to Gerrits design doc though.

lucamilanesio · 2025-09-03T08:38:13Z

docs/gerrit.md

+client. In practice, that means small, clean commits that evolve over
+time—exactly how Gerrit wants you to work.


Suggested change

client. In practice, that means small, clean commits that evolve over

time—exactly how Gerrit wants you to work.

client. In practice, that means small, clean commits that evolve over time,

exactly how Gerrit wants you to work.

lucamilanesio · 2025-09-03T08:40:34Z

docs/gerrit.md

+$ jj git init --colocate
+
+# Option 2: Add a Gerrit remote to a JJ repo
+$ jj git remote add gerrit ssh://gerrit.example.com:29418/your/project


Suggested change

$ jj git remote add gerrit ssh://gerrit.example.com:29418/your/project

$ jj git remote add gerrit https://review.gerrithub.io/yourname/yourproject

If you use Git/HTTPS is going to be more similar to a real production use; also using GerritHub.io could help people experimenting it without having to setup Gerrit at all.

lucamilanesio · 2025-09-03T08:42:32Z

docs/gerrit.md

+4. A Git remote named `gerrit`, if present
+5. Otherwise, the command errors
+
+## Updating changes after review


Suggested change

## Updating changes after review

## Uploading a new patch-set to an existing Change

lucamilanesio · 2025-09-03T08:43:34Z

docs/gerrit.md

+
+## Updating changes after review
+
+To address review feedback, amend or rewrite your commits, then run `jj gerrit


Suggested change

To address review feedback, amend or rewrite your commits, then run `jj gerrit

To rework an existing Change, amending the content or rewrite the commit comments, then run `jj gerrit

lucamilanesio · 2025-09-03T08:45:05Z

docs/gerrit.md

+The Gerrit project is exploring support for native Jujutsu metadata ("jj
+headers") so Gerrit could understand Jujutsu change identity without requiring
+`Change-Id` footers. Until then, `jj gerrit upload` will add a Gerrit-compatible
+`Change-Id` when needed and push to `refs/for/<branch>`.


All of this is pretty much up in the air and subject to change; I'd just remove it for now.

lucamilanesio · 2025-09-03T08:45:19Z

docs/gerrit.md

+
+

Nit: empty lines

lucamilanesio · 2025-09-03T08:45:59Z

docs/index.md

@@ -23,4 +23,5 @@ You may want to jump to:
 - [Installation and Setup](install-and-setup.md)
 - [Tutorial and Birds-Eye View](tutorial.md)
 - [Working with GitHub](github.md)
+- [Working with Gerrit](gerrit.md)


I'd just sort them alphabetically to avoid being biased on the order.

lucamilanesio · 2025-09-03T08:46:17Z

mkdocs.yml

@@ -92,6 +92,7 @@ nav:
      - 'Installation and Setup': 'install-and-setup.md'
      - 'Tutorial and Birds-Eye View': 'tutorial.md'
      - 'Working with GitHub': 'github.md'
+      - 'Working with Gerrit': 'gerrit.md'


Same as above: let's sort them alphabetically.

DanieleSassoli requested a review from a team as a code owner September 1, 2025 09:58

DanieleSassoli changed the base branch from main to aseipp/push-uytvkxyqyspn September 1, 2025 09:58

DanieleSassoli changed the title ~~Add gerrit docs~~ Add Working with Gerrit docs Sep 1, 2025

DanieleSassoli changed the title ~~Add Working with Gerrit docs~~ docs: add working with gerrit section Sep 1, 2025

docs: add working with gerrit section

9342158

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.

DanieleSassoli force-pushed the add_gerrit_docs branch from 586bc96 to 9342158 Compare September 1, 2025 14:12

matts1 requested changes Sep 2, 2025

View reviewed changes

talios reviewed Sep 2, 2025

View reviewed changes

PhilipMetzger reviewed Sep 2, 2025

View reviewed changes

lucamilanesio reviewed Sep 3, 2025

View reviewed changes

docs/gerrit.md

Comment on lines +114 to +115

Copy link

lucamilanesio Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: empty lines

lucamilanesio reviewed Sep 3, 2025

View reviewed changes


		## Updating changes after review

		To address review feedback, amend or rewrite your commits, then run `jj gerrit

		client. In practice, that means small, clean commits that evolve over
		time—exactly how Gerrit wants you to work.

	$ jj git remote add gerrit ssh://gerrit.example.com:29418/your/project
	$ jj git remote add gerrit https://review.gerrithub.io/yourname/yourproject

	## Updating changes after review
	## Uploading a new patch-set to an existing Change

	To address review feedback, amend or rewrite your commits, then run `jj gerrit
	To rework an existing Change, amending the content or rewrite the commit comments, then run `jj gerrit

docs: add working with gerrit section #7396

Are you sure you want to change the base?

docs: add working with gerrit section #7396

Conversation

DanieleSassoli commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

PhilipMetzger commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matts1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matts1 Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matts1 Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matts1 Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matts1 commented Sep 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PhilipMetzger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DanieleSassoli commented Sep 1, 2025 •

edited

Loading

PhilipMetzger commented Sep 1, 2025 •

edited

Loading

matts1 Sep 1, 2025 •

edited

Loading

matts1 Sep 2, 2025 •

edited

Loading

matts1 Sep 2, 2025 •

edited

Loading