gerrit/Documentation/user-upload.txt

= 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 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.

[[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%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.

[[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.

Pushing directly to `refs/changes/` is deprecated. If you see the error
message 'upload to refs/changes not allowed', it means that pushing directly
to `refs/changes` is disabled on the Gerrit server and the below section does
not apply to you.
--

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.


[[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 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
---------