GIT-REVIEW(1)

🎀 NAME 🎀

okay bestie, meet git-review — she takes your changes and submits them to Gerrit for review. 💅 that's it, that's the whole assignment, periodt.

---

✨ SYNOPSIS ✨

here's how you actually call her, fr fr:

git-review [-r remote] [-uv] -d change [branch]
git-review [-r remote] [-uv] -x change [branch]
git-review [-r remote] [-uv] -N change [branch]
git-review [-r remote] [-uv] -X change [branch]
git-review [-r remote] [-uv] -m change-ps-range [branch]
git-review [-r remote] [-fnuv] -s [branch]
git-review [-fnuvDRT] [-r remote] [-t topic] [--reviewers reviewer ...]
           [--notify type] [branch]
git-review -l [branch]
git-review --version

---

🌸 DESCRIPTION 🌸

so git-review automates and streamlines some of the tasks involved with submitting local changes to a Gerrit server for review. she's literally designed to make it easier to comprehend Gerrit, especially for users that have recently switched to Git from another version control system. 🫶 no gatekeeping here, we've all been the new girl.

now about change, bestie, listen up: change can be changeNumber as obtained using the --list option, or it can be changeNumber,patchsetNumber for fetching the exact patchset from the change. 👀 and when it's that second one? your local branch name will have a -patch[patchsetNumber] suffix. iconic, honestly.

🛠️ The following options are available

• -d change, --download=change — download change from Gerrit straight into a local branch 🫳 and that branch gets named after the change number. if the local branch already exists? she'll attempt to update it with the latest patchset for this change. slay.
• -x change, --cherrypick=change — apply change from Gerrit and commit it into the current local branch (a "cherry pick" 🍒). no additional branch is created. this makes it possible to review a change without making a local branch for it. but on the other hand, be aware: if you're not careful, this can easily result in additional patchsets for dependent changes 😭. also, if the current branch is different enough, the change may not apply at all, or it may produce merge conflicts that you have to resolve by hand. not a vibe.
• -N change, --cherrypickonly=change — apply change from Gerrit into the current working directory, add it to the staging area (the "git index"), but do not commit it. this makes it possible to review a change without creating a local commit for it. useful if you want to merge several commits into one that will be submitted for review. if the current branch is different enough, the change may not apply at all, or it may produce merge conflicts that need to be resolved by hand.
• -X change, --cherrypickindicate=change — apply change from Gerrit and commit it into the current local branch (a "cherry pick"), and this time she indicates which commit this change was cherry-picked from. this makes it possible to re-review a change for a different branch without creating a local branch for it. if the current branch is different enough, the change may not apply at all, or it may produce merge conflicts that need to be resolved by hand.
• -i, --new-changeid — force git-review to generate a new Change-Id, even if one already exists in the changelog. ✨ fresh start energy.
• -m change-ps-range, --compare=change-ps-range — download the specified patchsets for change from Gerrit, rebase both on master, and display the differences (git-diff). 🔍

change-ps-range can be specified as changeNumber,oldPatchSetNumber[-newPatchSetNumber]

oldPatchSetNumber is mandatory, and if newPatchSetNumber is not specified, the latest patchset will be used. this makes it possible to easily compare what has changed from last time you reviewed the proposed change. 👑

if the master branch is different enough, the rebase can produce merge conflicts. if that happens, rebasing will be aborted and the diff will be displayed for the not-rebased branches. you can also use --no-rebase (-R) to always skip the test rebase, or --keep-rebase (-K) to keep the incomplete state rather than having it automatically aborted. 💅

• -f, --finish — close down the local branch and switch back to the target branch on successful submission. bye bestie, you ate. 🎀
• -F, --force-rebase — force a rebase before doing anything else, even if it's not otherwise needed. unlike the normal test rebase, this rebase will be kept. use it if you know you want to push a commit automatically rebased onto the current state of the target branch. this is discouraged if you're amending an existing change, since it creates unnecessary additional differences from the previous revision and so makes things harder for reviewers of your changes. don't do your reviewers dirty like that. 😤
• -n, --dry-run — don't actually perform any commands that have direct effects. just print them instead. ✨ manifesting, but make it Git.
• -r remote, --remote=remote — the Git remote to use for Gerrit.
• --remote-hook — when installing the commit-msg hook, fetch it from the remote rather than using the built-in version. 🌈
• -s, --setup — just run the repo setup commands but don't submit anything. lowkey the "get ready with me" option.
• -t topic, --topic=topic — sets the target topic for this change on the Gerrit server.
• -T, --no-topic — submit review without a topic (this is the default).
• --hashtags=taglist — a comma-separated list of hashtag strings for this change. no spaces allowed. 💀
• --message=message — optional quoted message to include with the patchset. 💬
• -p, --private — send the patch as a private patch ready for review. Gerrit versions >= 2.15.
• -P, --remove-private — send a patch that is already in private state to normal patch. Gerrit versions >= 2.15.
• -w, --wip, --work-in-progress — send the patch as work in progress, for Gerrit versions >= 2.15. 🚧 not done yet bestie, don't look.
• -W, --ready — send a patch that's already work in progress as ready for review. Gerrit versions >= 2.15. ✨ the glow-up option.
• --cc reviewer ... — carbon copy one or more reviewers to the uploaded patchsets. reviewers should be identifiable by Gerrit (usually use their Gerrit username or email address). 📧
• --reviewers reviewer ... — subscribe one or more reviewers to the uploaded patchsets. reviewers should be identifiable by Gerrit (usually use their Gerrit username or email address).
• --notify type — control to whom email notifications are sent. possible values are NONE, OWNER, OWNER_REVIEWERS, ALL (the last one is the default). 🔔
• -u, --update — skip cached local copies and force updates from network resources. no stale data in this house.
• -l, --list — list the available reviews on the Gerrit server for this project. 🗒️
• -y, --yes — indicate that you do, in fact, understand, if you are submitting more than one patch. like, yes bestie, I know, I'm sure. 💅
• -v, --verbose — turns on more verbose output. she will tell you everything and honestly? we love a transparent queen.
• -R, --no-rebase — don't test for possible merge conflicts with the target branch before pushing. if the test rebase detects no merge conflicts, then the rebase is undone and your previous state is pushed. if merge conflicts are detected, git-review exits with the rebase in progress, allowing you to address it manually. by default git-review will never push the results of a rebase without your explicit involvement. 🛑

use this option to skip the merge conflict test, allowing you to push merge conflicts. yes, that means conflicts can go up. you've been warned.

also can be used for --compare to skip automatic rebase of fetched reviews.

• -K, --keep-rebase — if the test rebase before pushing fails, keep the incomplete rebase state in the worktree rather than automatically aborting it to clean up. 🫶 you get to keep the mess and deal with it yourself.
• --no-thin — disable thin pushes when pushing to Gerrit. this should only be used if you are currently experiencing unpack failures due to missing trees. it should not be required in typical day to day use. fr fr, don't touch this unless you have to.
• --color always|never|auto — enable or disable color output. default is "auto". 🎨
• --no-color — same thing as --color=never. 💅
• --no-custom-script — do not run scripts installed as hooks/{action}-review, where action is one of "pre" or "post". 🚫
• --track — choose the branch to submit the change against (and, if rebasing, to rebase against) from the branch being tracked (if a branch is being tracked), and set the tracking branch when downloading a change to point to the remote and branch against which patches should be submitted. see the gitreview.track configuration. 🌱
• --no-track — ignore any branch being tracked by the current branch, overriding gitreview.track. this option is implied by providing a specific branch name on the command line.
• --use-pushurl — use the pushurl option for the origin remote rather than conventional separate Gerrit remotes. 🔗
• --license — print the license text and exit. 📜
• --version — print the version number and exit. ⭐
• --help — print the short help message and exit. 🙋‍♀️ bestie needs a little help sometimes and that's okay.

⚙️ CONFIGURATION ✨

bestie, you can tune this whole utility by dropping entries into your Git config. yep, that's it. here's every single key that's supported 👑

gitreview.username 🫶

the default username used to access the repository. if it's not specified in the Git configuration, the Git remote, or the .gitreview file, then the user is gonna get prompted to type in the username. no cap.

example entry in the .gitconfig file:

[gitreview]
username=mygerrituser

gitreview.scheme 🌈

this setting decides the default scheme (ssh/http/https) of the gerrit remote.

gitreview.host 🌸

this setting decides the default hostname of the gerrit remote.

gitreview.port 🎀

this setting decides the default port of the gerrit remote.

gitreview.project 💜

this setting decides the default name of the gerrit git repo.

gitreview.remote 🦋

this setting decides the default name to use for the gerrit remote.

gitreview.branch ⭐

this setting decides the default branch.

gitreview.notopic 💀

set to true to never submit with a default topic (deprecated). this is the default behavior and this option has no effect — it's literally just vibing there for backwards compatability and may be removed in a future version of git-review.

so yeah, don't bother, it does nothing. iconic but useless 💅

gitreview.track 🔥

this one decides whether to prefer the currently-tracked branch (if there is one) and the branch against which the changeset was submitted to Gerrit (if there's exactly one such branch) over the defaultremote and defaultbranch for submitting and rebasing against. so if your local topic branch is tracking a remote branch, then the remote and branch that the local topic branch is tracking should be used for submit and rebase operations instead of defaultremote and defaultbranch. periodt.

when downloading a patch, it creates the local branch to track the appropriate remote and branch, so that branch gets chosen by default when you're submitting modifications to that changeset.

you should specify a value of true or false.

• true — do prefer the currently-tracked branch (if any) — equivalent to setting --track when submitting changes.
• false — ignore tracking branches — equivalent to setting --no-track (the default) or providing an explicit branch name when submitting changes. this is the default value unless it's overridden by the .gitreview file, and it's implied by providing a specific branch name on the command line.

gitreview.usepushurl 🌟

this setting decides whether to use a separate Git remote for the Gerrit connection, or to set pushurl on the remote origin.

you should specify a value of true or false.

• false — do not use pushurl and instead use a separate remote.
• true — use pushurl for interacting with Gerrit.

gitreview.rebase 🧚

this setting decides whether changes submitted will be rebased to the newest state of the branch.

you should specify a value of true or false.

• false — do not rebase changes on submit — equivalent to setting -R when submitting changes.
• true — do rebase changes on submit. this is the default value unless overridden by the .gitreview file.

this setting takes precedence over repository-specific configuration in the .gitreview file. so it wins the argument, as it should 💅

gitreview.branchauthor 🍓

this setting changes the look of the author part when naming the local branch of a downloaded change. the value must be one of "name", "email", or "username". default is "name". see also the --download option.

color.review 🌈

whether to use ANSI escape sequences to add color to the output displayed by this command. the default value is determined by color.ui.

• auto or true — if you want output to use color when written to the terminal (default with Git 1.8.4 and newer).
• always — if you want all output to use color.
• never or false — if you wish not to use color for any output. (default with Git older than 1.8.4)

---

git-review will query the git credential system for the Gerrit user/password when authentication failed over http(s). unlike git, git-review does not persist the Gerrit user/password in the git credential system, for security purposes, and the git credential system configuration stays under user responsibility. so like, that part is on you bestie 🫶

---

📁 FILES 🌸

to use git-review with your project, it's recommended that you create a file at the root of the repository named .gitreview and place info about your Gerrit installation in it. the format is similar to the Windows .ini file format:

[gerrit]
host=hostname
port=TCP port number of gerrit
project=project name
defaultbranch=branch to work on

it's also possible to specify an optional default name for the Git remote using the defaultremote configuration parameter.

setting defaultrebase to zero will make git-review not rebase changes by default (same as the -R command line option).

[gerrit]
scheme=ssh
host=review.example.com
port=29418
project=department/project.git
defaultbranch=master
defaultremote=review
defaultrebase=0
track=0

when the same option is provided through FILES and CONFIGURATION, the CONFIGURATION value wins. no debate 💅

---

🩺 DIAGNOSTICS 💀

normally, exit status is 0 if executed successfully. exit status 1 indicates a general error, and sometimes more specific error codes are available:

• 2 — Gerrit commit-msg hook could not be successfully installed.
• 3 — could not parse malformed argument value or user input.
• 32 — cannot fetch list of open changesets from Gerrit.
• 33 — cannot parse list of open changesets received from Gerrit.
• 34 — cannot query information about changesets.
• 35 — cannot fetch information about the changeset to be downloaded.
• 36 — changeset not found.
• 37 — particular patchset cannot be fetched from the remote git repository.
• 38 — specified patchset number not found in the changeset.
• 39 — invalid patchsets for comparison.
• 40 — connection to Gerrit was closed.
• 64 — cannot checkout downloaded patchset into the new branch.
• 65 — cannot checkout downloaded patchset into existing branch.
• 66 — cannot hard reset working directory and git index after download.
• 67 — cannot switch to some other branch when trying to finish the current branch.
• 68 — cannot delete current branch.
• 69 — requested patchset cannot be fully applied to the current branch. this exit status gets returned when there are merge conflicts with the current branch. possible reasons include an attempt to apply a patchset from a different branch or code. this exit status will also be returned if the patchset is already applied to the current branch. 😭
• 70 — cannot determine top level Git directory or .git subdirectory path.
• 101 — unauthorized (401) http request done by git-review.
• 104 — not found (404) http request done by git-review.

exit status larger than 31 indicates a problem with communication with Gerrit or the remote Git repository. exit status larger than 63 means there was a problem with a local repository or a working copy.

exit status larger than or equal to 128 means internal error in running the "git" command.

---

🧪 EXAMPLES 🔥

to fetch a remote change number 3004:

$ git-review -d 3004
Downloading refs/changes/04/3004/1 from gerrit into
review/3004
Switched to branch 'review/3004
$ git branch
  master
* review/3004

to fetch a remote patchset number 5 from change number 3004:

$ git-review -d 3004,5
Downloading refs/changes/04/3004/5 from gerrit into
review/3004-patch5
Switched to branch 'review/3004-patch5
$ git branch
  master
* review/3004-patch5

to send a change for review and delete the local branch afterwards:

$ git-review -f
remote: Resolving deltas:   0% (0/8)
To ssh://username@review.example.com/department/project.git
 * [new branch]      HEAD -> refs/for/master
Switched to branch 'master'
Deleted branch 'review/somenumber'
$ git branch
* master

an example .gitreview configuration file for a project department/project hosted on review.example.com port 29418 in the branch master:

[gerrit]
host=review.example.com
port=29418
project=department/project.git
defaultbranch=master

---

🐛 BUGS 🐛

bug reports can be submitted to https://storyboard.openstack.org/#!/project/opendev/git-review

---

👑 AUTHORS ✨

git-review is maintained by OpenDev Contributors 🫶

this manpage has been enhanced by:

• Antoine Musso <hashar@free.fr>
• Jeremy Stanley <fungi@yuggoth.org>
• Marcin Cieslak <saper@saper.info>
• Pavel Sedlák <psedlak@redhat.com>

---

and that's the whole page bestie, you ate that 💅 the version that got stamped on this one is 2021-02-09 and it answers to the name GIT-REVIEW(1) 🎀 go forth and review, you're the main character now 👑