![Dave Borowitz](/assets/img/avatar_default.png)
Sometimes surprising commits unintentionally end up in history, for example by direct push. It may be useful in such cases to open up a new post-commit code review for those commits. Allow users to create a new change for a *single* merged commit by appending %merged to a push: git push origin merged-commit:refs/for/master%merged Only a single commit is supported initially, to avoid a potentially expensive walk of history to discover commits that don't have associated changes, of which there may be very many. Post-commit code review was historically not supported by Gerrit at all, but this is a step in that direction. Change-Id: I4de55806cb8614b8c4d86b5de9bebc2f6923b927
554 lines
19 KiB
Plaintext
554 lines
19 KiB
Plaintext
= Gerrit Code Review - Uploading Changes
|
|
|
|
Gerrit supports three methods of uploading changes:
|
|
|
|
* Use `repo upload`, to create changes for review
|
|
* Use `git push`, to create changes for review
|
|
* Use `git push`, and bypass code review
|
|
|
|
All three methods rely on authentication, which must first be configured
|
|
by the uploading user.
|
|
|
|
Gerrit supports two methods of authenticating the uploading user. SSH
|
|
public key, and HTTP/HTTPS.
|
|
|
|
[[http]]
|
|
== HTTP/HTTPS
|
|
|
|
On Gerrit installations that do not support SSH authentication, the
|
|
user must authenticate via HTTP/HTTPS.
|
|
|
|
When link:config-gerrit.html#auth.gitBasicAuth[gitBasicAuth] is enabled,
|
|
the user is authenticated using standard BasicAuth and credentials validated
|
|
using the randomly generated HTTP password on the `HTTP Password` tab
|
|
in the user settings page or against LDAP when configured for the Gerrit Web UI.
|
|
|
|
When gitBasicAuth is not configured, the user's HTTP credentials can be
|
|
accessed within Gerrit by going to `Settings`, and then accessing the `HTTP
|
|
Password` tab.
|
|
|
|
For Gerrit installations where an link:config-gerrit.html#auth.httpPasswordUrl[HTTP password URL]
|
|
is configured, the password can be obtained by clicking on `Obtain Password`
|
|
and then following the site-specific instructions. On sites where this URL is
|
|
not configured, the password can be obtained by clicking on `Generate Password`.
|
|
|
|
[[ssh]]
|
|
== SSH
|
|
|
|
Each user uploading changes to Gerrit must configure one or more SSH
|
|
public keys. The per-user SSH key list can be accessed over the web
|
|
within Gerrit by `Settings`, and then accessing the `SSH Public Keys`
|
|
tab.
|
|
|
|
[[configure_ssh]]
|
|
=== Configuration
|
|
|
|
To register a new SSH key for use with Gerrit, paste the contents of
|
|
your `id_rsa.pub` or `id_dsa.pub` file into the text box and click
|
|
the add button. Gerrit only understands SSH version 2 public keys.
|
|
Keys may be supplied in either the OpenSSH format (key starts with
|
|
`ssh-rsa` or `ssh-dss`) or the RFC 4716 format (file starts with
|
|
`---- BEGIN SSH2 PUBLIC KEY ----`).
|
|
|
|
Typically SSH keys are stored in your home directory, under `~/.ssh`.
|
|
If you don't have any keys yet, you can create a new one and protect
|
|
it with a passphrase:
|
|
|
|
----
|
|
ssh-keygen -t rsa
|
|
----
|
|
|
|
Then copy the content of the public key file onto your clipboard,
|
|
and paste it into Gerrit's web interface:
|
|
|
|
----
|
|
cat ~/.ssh/id_rsa.pub
|
|
----
|
|
|
|
[TIP]
|
|
Users who frequently upload changes will also want to consider
|
|
starting an `ssh-agent`, and adding their private key to the list
|
|
managed by the agent, to reduce the frequency of entering the
|
|
key's passphrase. Consult `man ssh-agent`, or your SSH client's
|
|
documentation, for more details on configuration of the agent
|
|
process and how to add the private key.
|
|
|
|
[[test_ssh]]
|
|
=== Testing Connections
|
|
|
|
To verify your SSH key is working correctly, try using an SSH client
|
|
to connect to Gerrit's SSHD port. By default Gerrit runs on
|
|
port 29418, using the same hostname as the web server:
|
|
|
|
----
|
|
$ ssh -p 29418 sshusername@hostname
|
|
|
|
**** Welcome to Gerrit Code Review ****
|
|
|
|
Hi John Doe, you have successfully connected over SSH.
|
|
|
|
Unfortunately, interactive shells are disabled.
|
|
To clone a hosted Git repository, use:
|
|
|
|
git clone ssh://sshusername@hostname:29418/REPOSITORY_NAME.git
|
|
|
|
Connection to hostname closed.
|
|
----
|
|
|
|
In the command above, `sshusername` was configured as `Username` on
|
|
the `Profile` tab of the `Settings` screen. If it is not set,
|
|
propose a name and use `Select Username` to select the name.
|
|
|
|
To determine the port number Gerrit is running on, visit the special
|
|
information URL `http://'hostname'/ssh_info`, and copy the port
|
|
number from the second field:
|
|
|
|
----
|
|
$ curl http://hostname/ssh_info
|
|
hostname 29418
|
|
----
|
|
|
|
If you are developing an automated tool to perform uploads to Gerrit,
|
|
let the user supply the hostname or the web address for Gerrit,
|
|
and obtain the port number on the fly from the `/ssh_info` URL.
|
|
The returned output from this URL is always `'hostname' SP 'port'`,
|
|
or `NOT_AVAILABLE` if the SSHD server is not currently running.
|
|
|
|
|
|
== git push
|
|
|
|
[[push_create]]
|
|
=== Create Changes
|
|
|
|
To create new changes for review, simply push to the project's
|
|
magical `refs/for/'branch'` ref using any Git client tool:
|
|
|
|
----
|
|
git push ssh://sshusername@hostname:29418/projectname HEAD:refs/for/branch
|
|
----
|
|
|
|
E.g. `john.doe` can use git push to upload new changes for the
|
|
`experimental` branch of project `kernel/common`, hosted at the
|
|
`git.example.com` Gerrit server:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental
|
|
----
|
|
|
|
Each new commit uploaded by the `git push` client will be
|
|
converted into a change record on the server. The remote ref
|
|
`refs/for/experimental` is not actually created by Gerrit, even
|
|
though the client's status messages may say otherwise.
|
|
|
|
Other users (e.g. project owners) who have configured Gerrit to
|
|
notify them of new changes will be automatically sent an email
|
|
message when the push is completed.
|
|
|
|
[[push_options]]
|
|
=== Push Options
|
|
|
|
Additional options may be specified when pushing changes.
|
|
|
|
[[notify]]
|
|
==== Email Notifications
|
|
|
|
Uploaders can control to whom email notifications are sent by setting
|
|
the `notify` option:
|
|
|
|
* `NONE`: No email notification will be sent to anyone.
|
|
* `OWNER`: Only the change owner is notified.
|
|
* `OWNER_REVIEWERS`: Only owners and reviewers will be notified. This
|
|
includes all reviewers, existing reviewers of the change and new
|
|
reviewers that are added by the `reviewer` option or by mentioning
|
|
in the commit message.
|
|
* `ALL`: All email notifications will be sent. This includes
|
|
notifications to watchers, users that have starred the change, CCs
|
|
and the committer and author of the uploaded commit.
|
|
|
|
By default all email notifications are sent.
|
|
|
|
----
|
|
git push ssh://bot@git.example.com:29418/kernel/common HEAD:refs/for/master%notify=NONE
|
|
----
|
|
|
|
[[topic]]
|
|
==== Topic
|
|
|
|
To include a short tag associated with all of the changes in the
|
|
same group, such as the local topic branch name, append it after
|
|
the destination branch name or add it with the command line flag
|
|
`--push-option`, aliased to `-o`. In this example the short topic
|
|
tag 'driver/i42' will be saved on each change this push creates or
|
|
updates:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%topic=driver/i42
|
|
|
|
// this is the same as:
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental -o topic=driver/i42
|
|
----
|
|
|
|
[[message]]
|
|
==== Message
|
|
|
|
A comment message can be applied to the change by using the `message` (or `m`)
|
|
option:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%m=This_is_a_rebase_on_master
|
|
----
|
|
|
|
[NOTE]
|
|
git push refs parameter does not allow spaces. Use the '_' character instead,
|
|
it will then be applied as "This is a rebase on master".
|
|
|
|
[[review_labels]]
|
|
==== Review Labels
|
|
|
|
Review labels can be applied to the change by using the `label` (or `l`)
|
|
option in the reference:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%l=Verified+1
|
|
----
|
|
|
|
The `l='label[score]'` option may be specified more than once to
|
|
apply multiple review labels.
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%l=Code-Review+1,l=Verified+1
|
|
----
|
|
|
|
The value is optional. If not specified, it defaults to +1 (if
|
|
the label range allows it).
|
|
|
|
[[change_edit]]
|
|
==== Change Edits
|
|
|
|
A change edit can be pushed by specifying the `edit` (or `e`) option on
|
|
the reference:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%edit
|
|
----
|
|
|
|
There is at most one change edit per user and change. In order to push
|
|
a change edit the change must already exist.
|
|
|
|
[NOTE]
|
|
When a change edit already exists for a change then pushing with
|
|
`%edit` replaces the existing change edit. This option is useful to
|
|
rebase a change edit on the newest patch set when the rebase of the
|
|
change edit in the web UI fails due to conflicts.
|
|
|
|
If you are frequently uploading changes to the same Gerrit server,
|
|
consider adding an SSH host block in `~/.ssh/config` to remember
|
|
your username, hostname and port number. This permits the use of
|
|
shorter URLs on the command line, such as:
|
|
|
|
----
|
|
$ cat ~/.ssh/config
|
|
...
|
|
Host tr
|
|
Hostname git.example.com
|
|
Port 29418
|
|
User john.doe
|
|
|
|
$ git push tr:kernel/common HEAD:refs/for/experimental
|
|
----
|
|
|
|
[[reviewers]]
|
|
==== Reviewers
|
|
|
|
Specific reviewers can be requested and/or additional 'carbon
|
|
copies' of the notification message may be sent by including the
|
|
`reviewer` (or `r`) and `cc` options in the reference:
|
|
|
|
----
|
|
git push tr:kernel/common HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com
|
|
----
|
|
|
|
The `r='email'` and `cc='email'` options may be specified as many
|
|
times as necessary to cover all interested parties. Gerrit will
|
|
automatically avoid sending duplicate email notifications, such as
|
|
if one of the specified reviewers or CC addresses had also requested
|
|
to receive all new change notifications.
|
|
|
|
If you are frequently sending changes to the same parties and/or
|
|
branches, consider adding a custom remote block to your project's
|
|
`.git/config` file:
|
|
|
|
----
|
|
$ cat .git/config
|
|
...
|
|
[remote "exp"]
|
|
url = tr:kernel/common
|
|
push = HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com
|
|
|
|
$ git push exp
|
|
----
|
|
|
|
|
|
[[push_replace]]
|
|
=== Replace Changes
|
|
|
|
To add an additional patch set to a change, ensure Change-Id
|
|
lines were created in the original commit messages, and just use
|
|
`git push URL HEAD:refs/for/...` as <<push_create,described above>>.
|
|
Gerrit Code Review will automatically match the commits back to
|
|
their original changes by taking advantage of the Change-Id lines.
|
|
|
|
If Change-Id lines are not present in the commit messages, consider
|
|
amending the message and copying the line from the change's page
|
|
on the web, and then using `git push` as described above.
|
|
|
|
If Change-Id lines are not available, then the user must use the
|
|
manual mapping technique described below.
|
|
|
|
For more about Change-Ids, see link:user-changeid.html[Change-Id Lines].
|
|
|
|
[[manual_replacement_mapping]]
|
|
==== Manual Replacement Mapping
|
|
|
|
[NOTE]
|
|
--
|
|
The remainder of this section describes a manual method of replacing
|
|
changes by matching each commit name to an existing change number.
|
|
End-users should instead prefer to use Change-Id lines in their
|
|
commit messages, as the process is then fully automated by Gerrit
|
|
during normal uploads.
|
|
|
|
See above for the preferred technique of replacing changes.
|
|
--
|
|
|
|
To add an additional patch set to a change, replacing it with an
|
|
updated version of the same logical modification, send the new
|
|
commit to the change's ref. For example, to add the commit whose
|
|
SHA-1 starts with `c0ffee` as a new patch set for change number
|
|
`1979`, use the push refspec `c0ffee:refs/changes/1979` as below:
|
|
|
|
----
|
|
git push ssh://sshusername@hostname:29418/projectname c0ffee:refs/changes/1979
|
|
----
|
|
|
|
This form can be combined together with `refs/for/'branchname'`
|
|
(above) to simultaneously create new changes and replace changes
|
|
during one network transaction.
|
|
|
|
For example, consider the following sequence of events:
|
|
|
|
----
|
|
$ git commit -m A ; # create 3 commits
|
|
$ git commit -m B
|
|
$ git commit -m C
|
|
|
|
$ git push ... HEAD:refs/for/master ; # upload for review
|
|
... A is 1500 ...
|
|
... B is 1501 ...
|
|
... C is 1502 ...
|
|
|
|
$ git rebase -i HEAD~3 ; # edit "A", insert D before B
|
|
; # now series is A'-D-B'-C'
|
|
$ git push ...
|
|
HEAD:refs/for/master
|
|
HEAD~3:refs/changes/1500
|
|
HEAD~1:refs/changes/1501
|
|
HEAD~0:refs/changes/1502 ; # upload replacements
|
|
----
|
|
|
|
At the final step during the push Gerrit will attach A' as a new
|
|
patch set on change 1500; B' as a new patch set on change 1501; C'
|
|
as a new patch set on 1502; and D will be created as a new change.
|
|
|
|
Ensuring D is created as a new change requires passing the refspec
|
|
`HEAD:refs/for/branchname`, otherwise Gerrit will ignore D and
|
|
won't do anything with it. For this reason it is a good idea to
|
|
always include the create change refspec when uploading replacements.
|
|
|
|
|
|
[[bypass_review]]
|
|
=== Bypass Review
|
|
|
|
Changes (and annotated tags) can be pushed directly into a
|
|
repository, bypassing the review process. This is primarily useful
|
|
for a project owner to create new branches, create annotated tags
|
|
for releases, or to force-update a branch whose history needed to
|
|
be rewritten.
|
|
|
|
Gerrit restricts direct pushes that bypass review to:
|
|
|
|
* `+refs/heads/*+`: any branch can be updated, created, deleted,
|
|
or rewritten by the pusher.
|
|
* `+refs/tags/*+`: annotated tag objects pointing to any other type
|
|
of Git object can be created.
|
|
|
|
To push branches, the proper access rights must be configured first.
|
|
Here follows a few examples of how to configure this in Gerrit:
|
|
|
|
* Update: Any existing branch can be fast-forwarded to a new commit.
|
|
This is the safest mode as commits cannot be discarded. Creation
|
|
of new branches is rejected. Can be configured with
|
|
link:access-control.html#category_push_direct['Push'] access.
|
|
* Create: Allows creation of a new branch if the name does not
|
|
already designate an existing branch name. Needs
|
|
link:access-control.html#category_create['Create Reference']
|
|
configured. Please note that once created, this permission doesn't
|
|
grant the right to update the branch with further commits (see above
|
|
for update details).
|
|
* Delete: Implies Update, but also allows an existing
|
|
branch to be deleted. Since a force push is effectively a delete
|
|
followed by a create, but performed atomically on the server and
|
|
logged, this also permits forced push updates to branches.
|
|
To grant this access, configure
|
|
link:access-control.html#category_push_direct['Push'] with the
|
|
'Force' option ticked.
|
|
|
|
To push annotated tags, the `Create Annotated Tag` project right must
|
|
be granted to one (or more) of the user's groups. There is only
|
|
one level of access in this category.
|
|
|
|
Project owners may wish to grant themselves `Create Annotated Tag`
|
|
only at times when a new release is being prepared, and otherwise
|
|
grant nothing at all. This ensures that accidental pushes don't
|
|
make undesired changes to the public repository.
|
|
|
|
|
|
[[auto_merge]]
|
|
=== Auto-Merge during Push
|
|
|
|
Changes can be directly submitted on push. This is primarily useful
|
|
for teams that don't want to do code review but want to use Gerrit's
|
|
submit strategies to handle contention on busy branches. Using
|
|
`%submit` creates a change and submits it immediately:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%submit
|
|
----
|
|
|
|
On auto-merge of a change neither labels nor submit rules are checked.
|
|
If the merge fails the change stays open, but when pushing a new patch
|
|
set the merge can be reattempted by using `%submit` again.
|
|
|
|
This requires the caller to have link:access-control.html#category_submit[Submit]
|
|
permission on `refs/for/<ref>` (e.g. on `refs/for/refs/heads/master`).
|
|
Note how this is different from the `Submit` permission on `refs/heads/<ref>`,
|
|
and in particular you typically do not want to apply the `Submit` permission
|
|
on `refs/*` (unless you are ok with bypassing submit rules).
|
|
|
|
[[base]]
|
|
=== Selecting Merge Base
|
|
|
|
By default new changes are opened only for new unique commits
|
|
that have never before been seen by the Gerrit server. Clients
|
|
may override that behavior and force new changes to be created
|
|
by setting the merge base SHA-1 using the '%base' argument:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%base=$(git rev-parse origin/master)
|
|
----
|
|
|
|
It is also possible to specify more than one '%base' argument.
|
|
This may be useful when pushing a merge commit. Note that the '%'
|
|
character has only to be provided once, for the first '%base'
|
|
argument:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%base=commit-id1,base=commit-id2
|
|
----
|
|
|
|
[[merged]]
|
|
=== Creating Changes for Merged Commits
|
|
|
|
Normally, changes are only created for commits that have not yet
|
|
been merged into the branch. In some cases, you may want to review a
|
|
change that has already been merged. A new change for a merged commit
|
|
can be created by using the '%merged' argument:
|
|
|
|
----
|
|
git push ssh://john.doe@git.example.com:29418/kernel/common my-merged-commit:refs/for/master%merged
|
|
----
|
|
|
|
This only creates one merged change at a time, corresponding to
|
|
exactly `my-merged-commit`. It doesn't walk all of history up to that
|
|
point, which could be slow and create lots of unintended new changes.
|
|
To create multiple new changes, run push multiple times.
|
|
|
|
|
|
== repo upload
|
|
|
|
repo is a multiple repository management tool, most commonly
|
|
used by the Android Open Source Project. For more details, see
|
|
link:http://source.android.com/source/using-repo.html[using repo].
|
|
|
|
[[repo_create]]
|
|
=== Create Changes
|
|
|
|
To upload changes to a project using `repo`, ensure the manifest's
|
|
review field has been configured to point to the Gerrit server.
|
|
Only the hostname or the web address needs to be given in the
|
|
manifest file. During upload `repo` will automatically determine the
|
|
correct port number by reading `http://'reviewhostname'/ssh_info`
|
|
when its invoked.
|
|
|
|
Each new commit uploaded by `repo upload` will be converted into
|
|
a change record on the server. Other users (e.g. project owners)
|
|
who have configured Gerrit to notify them of new changes will be
|
|
automatically sent an email message. Additional notifications can
|
|
be sent through command line options.
|
|
|
|
For more details on using `repo upload`, see `repo help upload`.
|
|
|
|
[[repo_replace]]
|
|
=== Replace Changes
|
|
|
|
To replace changes, ensure Change-Id lines were created in the
|
|
commit messages, and just use `repo upload`.
|
|
Gerrit Code Review will automatically match the commits back to
|
|
their original changes by taking advantage of their Change-Id lines.
|
|
|
|
If Change-Id lines are not present in the commit messages, consider
|
|
amending the message and copying the line from the change's page
|
|
on the web.
|
|
|
|
If Change-Id lines are not available, then the user must use the much
|
|
more <<manual_replacement_mapping,manual mapping technique>> offered
|
|
by using `git push` to a specific `refs/changes/change#` reference.
|
|
|
|
For more about Change-Ids, see link:user-changeid.html[Change-Id Lines].
|
|
|
|
|
|
== Gritty Details
|
|
|
|
As Gerrit implements the entire SSH and Git server stack within its
|
|
own process space, Gerrit maintains complete control over how the
|
|
repository is updated, and what responses are sent to the `git push`
|
|
client invoked by the end-user, or by `repo upload`. This allows
|
|
Gerrit to provide magical refs, such as `+refs/for/*+` for new
|
|
change submission and `+refs/changes/*+` for change replacement.
|
|
When a push request is received to create a ref in one of these
|
|
namespaces Gerrit performs its own logic to update the database,
|
|
and then lies to the client about the result of the operation.
|
|
A successful result causes the client to believe that Gerrit has
|
|
created the ref, but in reality Gerrit hasn't created the ref at all.
|
|
|
|
By implementing the entire server stack, Gerrit is also able to
|
|
perform project level access control checks (to verify the end-user
|
|
is permitted to access a project) prior to advertising the available
|
|
refs, and potentially leaking information to a snooping client.
|
|
Clients cannot tell the difference between 'project not found' and
|
|
'project exists, but access is denied'.
|
|
|
|
Gerrit can also ensure users have completed a valid Contributor
|
|
Agreement prior to accepting any transferred objects, and if an
|
|
agreement is required, but not completed, it aborts the network
|
|
connection before data is sent. This ensures that project owners
|
|
can be certain any object available in their repository has been
|
|
supplied under at least one valid agreement.
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|