| :linkattrs: | |
| = 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 protocols for uploading changes; SSH and HTTP/HTTPS. These | |
| may not all be available for you, depending on the server configuration. | |
| [[http]] | |
| == HTTP/HTTPS | |
| On Gerrit installations that do not support SSH authentication, the | |
| user must authenticate via HTTP/HTTPS. | |
| The user is authenticated using standard BasicAuth. Depending on the | |
| value of link:#auth.gitBasicAuthPolicy[auth.gitBasicAuthPolicy], | |
| credentials are validated using: | |
| * The randomly generated HTTP password on the `HTTP Password` tab | |
| in the user settings page if `gitBasicAuthPolicy` is `HTTP`. | |
| * The LDAP password if `gitBasicAuthPolicy` is `LDAP` | |
| * Both, the HTTP and the LDAP passwords (in this order) if `gitBasicAuthPolicy` | |
| is `HTTP_LDAP`. | |
| When gitBasicAuthPolicy is set to `LDAP` or `HTTP_LDAP` and the user | |
| is authenticating with the LDAP username/password, the Git client config | |
| needs to have `http.cookieFile` set to a local file, otherwise every | |
| single call would trigger a full LDAP authentication and groups resolution | |
| which could introduce a noticeable latency on the overall execution | |
| and produce unwanted load to the LDAP server. | |
| When gitBasicAuthPolicy is not `LDAP`, the user's HTTP credentials can | |
| be regenerated by going to `Settings`, and then accessing the `HTTP | |
| Password` tab. Revocation can effectively be done by regenerating the | |
| password and then forgetting it. | |
| 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 | |
| To upload changes over SSH, Gerrit supports two forms of authentication: a | |
| user's public key or kerberos. | |
| Unless your Gerrit instance is configured to support | |
| link:config-gerrit.html#sshd.kerberosKeytab[kerberos] in your domain, only | |
| public key authentication can be used. | |
| [[configure_ssh_public_keys]] | |
| === Public keys | |
| 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. | |
| [[configure_ssh_kerberos]] | |
| === Kerberos | |
| A kerberos-enabled server configuration allows for zero configuration in an | |
| existing single-sign-on environment. | |
| Your SSH client should be configured to enable kerberos authentication. For | |
| OpenSSH clients, this is controlled by the option `GSSAPIAuthentication` which | |
| should be set to `yes`. | |
| Some Linux distributions have packaged OpenSSH to enable this by default (e.g. | |
| Debian, Ubuntu). If this is not the case for your distribution, enable it for | |
| Gerrit with this entry in your local SSH configuration: | |
| ---- | |
| Host gerrit.mydomain.tld | |
| GSSAPIAuthentication yes | |
| ---- | |
| [[test_ssh]] | |
| === Testing Connections | |
| To verify your SSH authentication 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. | |
| [[configure_ssh_host_entry]] | |
| === OpenSSH Host entry | |
| If you are frequently uploading changes to the same Gerrit server, consider | |
| adding an SSH `Host` entry in your OpenSSH client configuration | |
| (`~/.ssh/config`) for that Gerrit server. It allows you use a single alias | |
| defining your username, hostname and port number whenever you're accessing | |
| this Gerrit server in an SSH context (also command line SSH or SCP). Use this | |
| for easier to remember, shorter URLs, e.g.: | |
| ---- | |
| $ cat ~/.ssh/config | |
| ... | |
| Host mygerrit | |
| Hostname git.example.com | |
| Port 29418 | |
| User john.doe | |
| $ git clone mygerrit:myproject | |
| $ ssh mygerrit gerrit version | |
| $ scp -p mygerrit:hooks/commit-msg .git/hooks/ | |
| ---- | |
| == 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 | |
| ---- | |
| In addition uploaders can explicitly specify accounts that should be | |
| notified, regardless of the value that is given for the `notify` | |
| option. To notify a specific account specify it by an | |
| `notify-to='email'`, `notify-cc='email'` or `notify-bcc='email'` | |
| option. These options can 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 accounts | |
| had also requested to receive all new change notifications. The | |
| accounts that are specified by `notify-to='email'`, `notify-cc='email'` | |
| and `notify-bcc='email'` will only be notified about this one push. | |
| They are not added as link:#reviewers[reviewers or CCs], hence they are | |
| not automatically signed up to be notified on further updates of the | |
| change. | |
| ---- | |
| git push ssh://bot@git.example.com:29418/kernel/common HEAD:refs/for/master%notify=NONE,notify-to=a@a.com | |
| ---- | |
| [[topic]] | |
| ==== Topic | |
| To include a short link:intro-user.html#topics[topic] 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 name | |
| '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 | |
| ---- | |
| [[hashtag]] | |
| ==== Hashtag | |
| To include a link:intro-user.html#hashtags[hashtag] associated with all of the | |
| changes in the same group, use the `hashtag` or `t` option: | |
| ---- | |
| // these are all equivalent | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%hashtag=stable-fix | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%t=stable-fix | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental -o hashtag=stable-fix | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental -o t=stable-fix | |
| ---- | |
| [[private]] | |
| ==== Private Changes | |
| To push a private change or to turn a change private on push the `private` | |
| option can be specified: | |
| ---- | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%private | |
| ---- | |
| Omitting the `private` option when pushing updates to a private change | |
| doesn't make change non-private again. To remove the private | |
| flag from a change on push, explicitly specify the `remove-private` option: | |
| ---- | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%remove-private | |
| ---- | |
| [[wip]] | |
| ==== Work-In-Progress Changes | |
| To push a wip change or to turn a change to wip the `work-in-progress` (or `wip`) | |
| option can be specified: | |
| ---- | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%wip | |
| ---- | |
| Omitting the `wip` option when pushing updates to a wip change | |
| doesn't make change ready again. To remove the `wip` | |
| flag from a change on push, explicitly specify the `ready` option: | |
| ---- | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%ready | |
| ---- | |
| Only change owners, project owners and site administrators can specify | |
| `work-in-progress` and `ready` options on push. | |
| The default for this option can be set as a | |
| link:intro-user.html#work-in-progress-by-default[user preference]. If the | |
| preference is set so the default behavior is to create `work-in-progress` | |
| changes, this can be overridden with the `ready` option. | |
| [[patch_set_description]] | |
| ==== Patch Set Description | |
| A link:concept-patch-sets.html#_description[patch set description] can be | |
| applied 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%21 | |
| ---- | |
| [NOTE] | |
| git push refs parameter does not allow spaces. Use the '_' or '+' character | |
| to represent spaces, and percent-encoding to represent other special chars. | |
| The above example will thus be applied as "This is a rebase on master!" | |
| To avoid confusion in parsing the git ref, at least the following characters | |
| must be percent-encoded: " %^@.~-+_:/!". Note that some of the reserved | |
| characters (like tilde) are not escaped in the standard URL encoding rules, | |
| so a language-provided function (e.g. encodeURIComponent(), in JavaScript) | |
| might not suffice. To be safest, you might consider percent-encoding all | |
| non-alphanumeric characters (and all multibyte UTF-8 code points). | |
| [[publish-comments]] | |
| ==== Publish Draft Comments | |
| If you have draft comments on the change(s) that are updated by the push, the | |
| `publish-comments` option will cause them to be published: | |
| ---- | |
| git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%publish-comments | |
| ---- | |
| The default for this option can be set as a | |
| link:intro-user.html#publish-comments-on-push[user preference]. If the | |
| preference is set so the default behavior is to publish, this can be overridden | |
| with the `no-publish-comments` (or `np`) option. | |
| [[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. | |
| [[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 ssh://john.doe@git.example.com:29418/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 = ssh://john.doe@git.example.com:29418/kernel/common | |
| push = HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com | |
| $ git push exp | |
| ---- | |
| [[trace]] | |
| ==== Trace | |
| When pushing to Gerrit tracing can be enabled by setting the | |
| `trace=<trace-id>` push option. It is recommended to use the ID of the | |
| issue that is being investigated as trace ID. | |
| ---- | |
| git push -o trace=issue/123 ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master | |
| ---- | |
| It is also possible to omit the trace ID and get a unique trace ID | |
| generated. | |
| .Example Request | |
| ---- | |
| git push -o trace ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master | |
| ---- | |
| Enabling tracing results in additional logs with debug information that | |
| are written to the `error_log`. All logs that correspond to the traced | |
| request are associated with the trace ID. This trace ID is returned in | |
| the command output: | |
| ---- | |
| remote: TRACE_ID: 1534174322774-7edf2a7b | |
| ---- | |
| Given the trace ID an administrator can find the corresponding logs and | |
| investigate issues more easily. | |
| [[deadline]] | |
| ==== Setting a deadline | |
| When pushing to Gerrit it's possible that the client sets a deadline after which | |
| the push should be aborted. To do this the `deadline=<deadline>` push option | |
| must be set on the git push. Values must be specified using standard time unit | |
| abbreviations ('ms', 'sec', 'min', etc.). | |
| ---- | |
| git push -o deadline=10m ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master | |
| ---- | |
| Setting a deadline for the push overrides any | |
| link:config-gerrit.html#deadline.id[server-side deadline] that has been | |
| configured on the host, but not the link:config.html#receive.timeout[receive | |
| timeout]. | |
| [[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. | |
| For more about Change-Ids, see link:user-changeid.html[Change-Id Lines]. | |
| [[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. | |
| [[skip_validation]] | |
| === Skip Validation | |
| Even when a user has permission to push directly to a branch | |
| link:#bypass_review[bypassing review], by default Gerrit will still validate any | |
| new commits, for example to check author/committer identities, and run | |
| link:config-validation.html#new-commit-validation[validation plugins]. This | |
| behavior can be bypassed with a push option: | |
| ---- | |
| git push -o skip-validation HEAD:master | |
| ---- | |
| Using the `skip-validation` option requires the user to have a specific set | |
| of permissions, *in addition* to those permissions already required to bypass | |
| review: | |
| * link:access-control.html#category_forge_author[Forge Author] | |
| * link:access-control.html#category_forge_committer[Forge Committer] | |
| * link:access-control.html#category_forge_server[Forge Server] | |
| * link:access-control.html#category_push_merge[Push Merge Commits] | |
| Plus these additional requirements on the project: | |
| * Project must not link:project-configuration.html#require-signed-off-by[require | |
| Signed-off-by]. | |
| * Project must not have `refs/meta/reject-commits`. | |
| This option only applies when pushing directly to a branch bypassing review. | |
| Validation also occurs when pushing new changes for review, and that type of | |
| validation cannot be skipped. | |
| The `skip-validation` option is always required when pushing | |
| link:error-too-many-commits.html[more than a certain number of commits]. This is | |
| the recommended approach when pushing lots of old history, since some validators | |
| would require rewriting history in order to make them pass. | |
| [[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 are not part of any branch in refs/heads or the target | |
| branch. 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. | |
| [[ignore-attention-set]] | |
| === Ignore automatic attention set rules | |
| Normally, we add users to the attention set based on several rules such as adding | |
| reviewers, replying, and many others. The full rule list is in | |
| link:user-attention-set.html[Attention Set]. | |
| --ignore-automatic-attention-set-rules (also known as -ias and | |
| -ignore-attention-set) can be used to keep the attention set as it were before | |
| the push. | |
| ---- | |
| git push ssh://john.doe@git.example.com:29418/kernel/common my-merged-commit:refs/for/master%ias | |
| ---- | |
| == 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,role=external,window=_blank]. | |
| [[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. | |
| 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 review metadata, | |
| 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 | |
| --------- |