Documentation
¶
Overview ¶
Git-codereview manages the code review process for Git changes using a Gerrit server.
The git-codereview tool manages “change branches” in the local git repository. Each such branch tracks a single commit, or “pending change”, that is reviewed using a Gerrit server; the Gerrit remote must be named “origin” in the local git repo.
Modifications to the pending change are applied by amending the commit. This process implements the “single-commit feature branch” model. Creating multiple-commit feature branches, for example to break a large change into a reviewable sequence, is also supported; see the discussion below.
Each local git branch is expected to have a configured upstream branch on the server. For example, for a local “work” branch, .git/config might contain:
[branch "work"] remote = origin merge = refs/heads/main
to instruct git itself that the local “work” branch tracks the upstream “main” branch. Git-codereview inspects this setting, which is referred to as “upstream” below. If upstream is not configured, which can happen when using checkouts managed by very old versions of git-codereview or other tools, git-codereview initializes upstream to “main” if that branch exists, or else “master”.
Once installed as git-codereview, the tool's commands are available through git either by running
git codereview <command>
or, if aliases are installed, as
git <command>
The review tool's command names do not conflict with any extant git commands. This document uses the first form for clarity, but most users install these aliases in their .gitconfig file:
[alias] change = codereview change gofmt = codereview gofmt mail = codereview mail pending = codereview pending rebase-work = codereview rebase-work reword = codereview reword submit = codereview submit sync = codereview sync sync-branch = codereview sync-branch
Single-Commit Work Branches ¶
For simple, unrelated changes, the typical usage of the git-codereview tool is to place each pending change in its own Git branch. In this workflow, the work branch contains either no pending change beyond upstream (when there's no local work) or exactly one pending change beyond upstream (the change being developed).
When there is no pending change on the work branch, “git codereview change” creates one by running “git commit”. Otherwise, when there is already a pending change, “git codereview change” revises it by running “git commit --amend”.
The “git codereview mail” and “git codereview submit” commands implicitly operate on the lone pending change.
Multiple-Commit Work Branches ¶
Of course, it is not always feasible to put each pending change in a separate branch. A sequence of changes that build on one another is more easily managed as multiple commits on a single branch, and the git-codereview tool supports this workflow as well. To add a new pending change, invoke “git commit” directly, instead of “git codereview change”. The git-codereview tool adjusts its behavior when there are multiple pending changes.
The “git codereview change” command amends the top commit in the stack (HEAD). To amend a commit further down the stack, use Git's rebase support, for example by using “git commit --fixup” followed by “git codereview rebase-work”.
The “git codereview mail” command requires an explicit revision argument, but note that since “git codereview mail” is implemented as a “git push”, any commits earlier in the stack are necessarily also mailed.
The “git codereview submit” command also requires an explicit revision argument, and while earlier commits are necessarily still uploaded and mailed, only the named revision or revisions are submitted (merged into upstream). In a single-commit work branch, a successful “git codereview submit” effectively runs “git codereview sync” automatically. In a multiple-commit work branch, it does not, because the implied “git rebase” may conflict with the remaining pending commits. Instead it is necessary to run “git codereview sync” explicitly (when ready) after “git codereview submit”.
Reusing Work Branches ¶
Although one common practice is to create a new branch for each pending change, running “git codereview submit” (and possibly “git codereview sync”) leaves the current branch ready for reuse with a future change. Some developers find it helpful to create a single work branch (“git change work”) and then do all work in that branch, possibly in the multiple-commit mode, never changing between branches.
Commands ¶
All commands accept these global flags:
The -n flag prints all commands that would be run, but does not run them.
The -v flag prints all commands that make changes. Multiple occurrences trigger more verbosity in some commands, including sync.
These are omitted from the per-command descriptions below.
Branchpoint ¶
The branchpoint command prints the commit hash of the most recent commit on the current branch that is shared with the Gerrit server.
git codereview branchpoint
This commit is the point where local work branched from the published tree. The command is intended mainly for use in scripts. For example, “git diff $(git codereview branchpoint)” or “git log $(git codereview branchpoint)..HEAD”.
Change ¶
The change command creates and moves between Git branches and maintains the pending changes on work branches.
git codereview change [-a] [-q] [-m <message>] [branchname]
Given a branch name as an argument, the change command switches to the named branch, creating it if necessary. If the branch is created and there are staged changes, it will commit the changes to the branch, creating a new pending change.
With no argument, the change command creates a new pending change from the staged changes in the current branch or, if there is already a pending change, amends that change.
The -q option skips the editing of an extant pending change's commit message. If -m is present, -q is ignored.
The -a option automatically adds any unstaged edits in tracked files during commit; it is equivalent to the 'git commit' -a option.
The -m option specifies a commit message and skips the editor prompt. This option is only useful when creating commits (e.g. if there are unstaged changes). If a commit already exists, it is overwritten. If -q is also present, -q will be ignored.
The -s option adds a Signed-off-by trailer at the end of the commit message; it is equivalent to the 'git commit' -s option.
As a special case, if branchname is a decimal CL number, such as 987, the change command downloads the latest patch set of that CL from the server and switches to it. A specific patch set P can be requested by adding /P: 987.2 for patch set 2 of CL 987. If the origin server is GitHub instead of Gerrit, then the number is treated a GitHub pull request number, and the change command downloads the latest version of that pull request. In this case, the /P suffix is disallowed.
Gofmt ¶
The gofmt command applies the gofmt program to all files modified in the current work branch, both in the staging area (index) and the working tree (local directory).
git codereview gofmt [-l]
The -l option causes the command to list the files that need reformatting but not reformat them. Otherwise, the gofmt command reformats modified files in place. That is, files in the staging area are reformatted in the staging area, and files in the working tree are reformatted in the working tree.
Help ¶
The help command displays basic usage instructions.
git codereview help
Hooks ¶
The hooks command installs the Git hooks to enforce code review conventions.
git codereview hooks
The pre-commit hook checks that all Go code is formatted with gofmt and that the commit is not being made directly to a branch with the same name as the upstream branch.
The commit-msg hook adds the Gerrit “Change-Id” line to the commit message if not present. It also checks that the message uses the convention established by the Go project that the first line has the form, pkg/path: summary.
The hooks command will not overwrite an existing hook. This hook installation is also done at startup by all other git codereview commands, except “git codereview help”.
Hook-Invoke ¶
The hook-invoke command is an internal command that invokes the named Git hook.
git codereview hook-invoke <hook> [args]
It is run by the shell scripts installed by the “git codereview hooks” command.
Mail ¶
The mail command starts the code review process for the pending change.
git codereview mail [-r email,...] [-cc email,...] [-autosubmit] [-diff] [-f] [-hashtag tag,...] [-nokeycheck] [-topic topic] [-trybot] [-wip] [revision]
It pushes the pending change commit in the current branch to the Gerrit code review server and prints the URL for the change on the server. If the change already exists on the server, the mail command updates that change with a new changeset.
If there are multiple pending commits, the revision argument is mandatory. If no revision is specified, the mail command prints a short summary of the pending commits for use in deciding which to mail.
If any commit that would be pushed to the server contains the text “DO NOT MAIL” (case insensitive) in its commit message, the mail command will refuse to send the commit to the server.
The -r and -cc flags identify the email addresses of people to do the code review and to be CC'ed about the code review. Multiple addresses are given as a comma-separated list.
An email address passed to -r or -cc can be shortened from name@domain to name. The mail command resolves such shortenings by reading the list of past reviewers from the git repository log to find email addresses of the form name@somedomain and then, in case of ambiguity, using the reviewer who appears most often.