Shawn O. Pearce | e31d02c | 2009-12-08 12:21:37 -0800 | [diff] [blame] | 1 | Gerrit Code Review - Uploading Changes |
| 2 | ====================================== |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 3 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 4 | Gerrit supports three methods of uploading changes: |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 5 | |
| 6 | * Use `repo upload`, to create changes for review |
| 7 | * Use `git push`, to create changes for review |
| 8 | * Use `git push`, and bypass code review |
| 9 | |
David Pursehouse | baac425 | 2013-01-25 17:42:19 +0900 | [diff] [blame] | 10 | All three methods rely on authentication, which must first be configured |
| 11 | by the uploading user. |
| 12 | |
| 13 | Gerrit supports two methods of authenticating the uploading user. SSH |
| 14 | public key, and HTTP/HTTPS. |
| 15 | |
Edwin Kempin | 60ab853 | 2013-03-27 14:33:46 +0100 | [diff] [blame] | 16 | [[http]] |
David Pursehouse | baac425 | 2013-01-25 17:42:19 +0900 | [diff] [blame] | 17 | HTTP/HTTPS |
| 18 | ---------- |
| 19 | |
| 20 | On Gerrit installations that do not support SSH authentication, the |
| 21 | user must authenticate via HTTP/HTTPS. |
| 22 | |
| 23 | When link:config-gerrit.html#auth.gitBasicAuth[gitBasicAuth] is enabled, |
| 24 | the user is authenticated using standard BasicAuth and credentials validated |
| 25 | using the same authentication method configured for the Gerrit Web UI. |
| 26 | |
| 27 | When gitBasicAuth is not configured, the user's HTTP credentials can be |
| 28 | accessed within Gerrit by going to `Settings`, and then accessing the `HTTP |
| 29 | Password` tab. |
| 30 | |
| 31 | For Gerrit installations where an link:config-gerrit.html#auth.httpPasswordUrl[HTTP password URL] |
| 32 | is configured, the password can be obtained by clicking on `Obtain Password` |
| 33 | and then following the site-specific instructions. On sites where this URL is |
| 34 | not configured, the password can be obtained by clicking on `Generate Password`. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 35 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 36 | SSH |
| 37 | --- |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 38 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 39 | Each user uploading changes to Gerrit must configure one or more SSH |
| 40 | public keys. The per-user SSH key list can be accessed over the web |
Edwin Kempin | b5df3b8 | 2011-10-10 11:31:14 +0200 | [diff] [blame] | 41 | within Gerrit by `Settings`, and then accessing the `SSH Public Keys` |
| 42 | tab. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 43 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 44 | [[configure_ssh]] |
| 45 | Configuration |
| 46 | ~~~~~~~~~~~~~ |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 47 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 48 | To register a new SSH key for use with Gerrit, paste the contents of |
| 49 | your `id_rsa.pub` or `id_dsa.pub` file into the text box and click |
| 50 | the add button. Gerrit only understands SSH version 2 public keys. |
| 51 | Keys may be supplied in either the OpenSSH format (key starts with |
| 52 | `ssh-rsa` or `ssh-dss`) or the RFC 4716 format (file starts with |
| 53 | `---- BEGIN SSH2 PUBLIC KEY ----`). |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 54 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 55 | Typically SSH keys are stored in your home directory, under `~/.ssh`. |
| 56 | If you don't have any keys yet, you can create a new one and protect |
| 57 | it with a passphrase: |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 58 | |
| 59 | ==== |
| 60 | ssh-keygen -t rsa |
| 61 | ==== |
| 62 | |
| 63 | Then copy the content of the public key file onto your clipboard, |
| 64 | and paste it into Gerrit's web interface: |
| 65 | |
| 66 | ==== |
| 67 | cat ~/.ssh/id_rsa.pub |
| 68 | ==== |
| 69 | |
| 70 | [TIP] |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 71 | Users who frequently upload changes will also want to consider |
David Pursehouse | 221d4f6 | 2012-06-08 17:38:08 +0900 | [diff] [blame] | 72 | starting an `ssh-agent`, and adding their private key to the list |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 73 | managed by the agent, to reduce the frequency of entering the |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 74 | key's passphrase. Consult `man ssh-agent`, or your SSH client's |
| 75 | documentation, for more details on configuration of the agent |
| 76 | process and how to add the private key. |
| 77 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 78 | [[test_ssh]] |
| 79 | Testing Connections |
| 80 | ~~~~~~~~~~~~~~~~~~~ |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 81 | |
| 82 | To verify your SSH key is working correctly, try using an SSH client |
David Pursehouse | 221d4f6 | 2012-06-08 17:38:08 +0900 | [diff] [blame] | 83 | to connect to Gerrit's SSHD port. By default Gerrit runs on |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 84 | port 29418, using the same hostname as the web server: |
| 85 | |
| 86 | ==== |
Edwin Kempin | fb95a1b | 2011-10-05 10:08:00 +0200 | [diff] [blame] | 87 | .................................................................. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 88 | $ ssh -p 29418 sshusername@hostname |
Edwin Kempin | fb95a1b | 2011-10-05 10:08:00 +0200 | [diff] [blame] | 89 | |
| 90 | **** Welcome to Gerrit Code Review **** |
| 91 | |
| 92 | Hi John Doe, you have successfully connected over SSH. |
| 93 | |
| 94 | Unfortunately, interactive shells are disabled. |
| 95 | To clone a hosted Git repository, use: |
| 96 | |
| 97 | git clone ssh://sshusername@hostname:29418/REPOSITORY_NAME.git |
| 98 | |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 99 | Connection to hostname closed. |
Edwin Kempin | fb95a1b | 2011-10-05 10:08:00 +0200 | [diff] [blame] | 100 | .................................................................. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 101 | ==== |
| 102 | |
Edwin Kempin | fb95a1b | 2011-10-05 10:08:00 +0200 | [diff] [blame] | 103 | In the command above, `sshusername` was configured as `Username` on |
| 104 | the `Profile` tab of the `Settings` screen. If it is not set, |
| 105 | propose a name and use `Select Username` to select the name. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 106 | |
| 107 | To determine the port number Gerrit is running on, visit the special |
| 108 | information URL `http://'hostname'/ssh_info`, and copy the port |
| 109 | number from the second field: |
| 110 | |
| 111 | ==== |
| 112 | $ curl http://hostname/ssh_info |
| 113 | hostname 29418 |
| 114 | ==== |
| 115 | |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 116 | If you are developing an automated tool to perform uploads to Gerrit, |
| 117 | let the user supply the hostname or the web address for Gerrit, |
| 118 | and obtain the port number on the fly from the `/ssh_info` URL. |
| 119 | The returned output from this URL is always `'hostname' SP 'port'`, |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 120 | or `NOT_AVAILABLE` if the SSHD server is not currently running. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 121 | |
| 122 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 123 | git push |
| 124 | -------- |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 125 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 126 | [[push_create]] |
| 127 | Create Changes |
| 128 | ~~~~~~~~~~~~~~ |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 129 | |
David Pursehouse | 221d4f6 | 2012-06-08 17:38:08 +0900 | [diff] [blame] | 130 | To create new changes for review, simply push to the project's |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 131 | magical `refs/for/'branch'` ref using any Git client tool: |
| 132 | |
| 133 | ==== |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 134 | git push ssh://sshusername@hostname:29418/projectname HEAD:refs/for/branch |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 135 | ==== |
| 136 | |
| 137 | E.g. `john.doe` can use git push to upload new changes for the |
| 138 | `experimental` branch of project `kernel/common`, hosted at the |
| 139 | `git.example.com` Gerrit server: |
| 140 | |
| 141 | ==== |
| 142 | git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental |
| 143 | ==== |
| 144 | |
| 145 | Each new commit uploaded by the `git push` client will be |
| 146 | converted into a change record on the server. The remote ref |
| 147 | `refs/for/experimental` is not actually created by Gerrit, even |
| 148 | though the client's status messages may say otherwise. |
| 149 | |
| 150 | Other users (e.g. project owners) who have configured Gerrit to |
| 151 | notify them of new changes will be automatically sent an email |
| 152 | message when the push is completed. |
| 153 | |
Shawn O. Pearce | d50c94e | 2010-07-15 12:24:11 -0700 | [diff] [blame] | 154 | To include a short tag associated with all of the changes in the |
| 155 | same group, such as the local topic branch name, append it after |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 156 | the destination branch name. In this example the short topic tag |
Shawn O. Pearce | d50c94e | 2010-07-15 12:24:11 -0700 | [diff] [blame] | 157 | 'driver/i42' will be saved on each change this push creates or |
| 158 | updates: |
| 159 | |
| 160 | ==== |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 161 | git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%topic=driver/i42 |
Shawn O. Pearce | d50c94e | 2010-07-15 12:24:11 -0700 | [diff] [blame] | 162 | ==== |
| 163 | |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 164 | If you are frequently uploading changes to the same Gerrit server, |
| 165 | consider adding an SSH host block in `~/.ssh/config` to remember |
| 166 | your username, hostname and port number. This permits the use of |
| 167 | shorter URLs on the command line, such as: |
| 168 | |
| 169 | ==== |
| 170 | $ cat ~/.ssh/config |
| 171 | ... |
| 172 | Host tr |
| 173 | Hostname git.example.com |
| 174 | Port 29418 |
| 175 | User john.doe |
| 176 | |
| 177 | $ git push tr:kernel/common HEAD:refs/for/experimental |
| 178 | ==== |
| 179 | |
Edwin Kempin | b5df3b8 | 2011-10-10 11:31:14 +0200 | [diff] [blame] | 180 | Specific reviewers can be requested and/or additional 'carbon |
| 181 | copies' of the notification message may be sent by including these |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 182 | as options in the reference |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 183 | |
| 184 | ==== |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 185 | git push tr:kernel/common HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 186 | ==== |
| 187 | |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 188 | The `r='email'` and `cc='email'` options may be specified as many |
| 189 | times as necessary to cover all interested parties. Gerrit will |
| 190 | automatically avoid sending duplicate email notifications, such as |
| 191 | if one of the specified reviewers or CC addresses had also requested |
| 192 | to receive all new change notifications. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 193 | |
| 194 | If you are frequently sending changes to the same parties and/or |
| 195 | branches, consider adding a custom remote block to your project's |
| 196 | `.git/config` file: |
| 197 | |
| 198 | ==== |
| 199 | $ cat .git/config |
| 200 | ... |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 201 | [remote "exp"] |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 202 | url = tr:kernel/common |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 203 | push = HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 204 | |
Shawn Pearce | 69928a6 | 2013-02-24 18:01:27 -0800 | [diff] [blame] | 205 | $ git push exp |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 206 | ==== |
| 207 | |
| 208 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 209 | [[push_replace]] |
| 210 | Replace Changes |
| 211 | ~~~~~~~~~~~~~~~ |
| 212 | |
| 213 | To add an additional patch set to a change, ensure Change-Id |
| 214 | lines were created in the original commit messages, and just use |
| 215 | `git push URL HEAD:refs/for/...` as <<push_create,described above>>. |
| 216 | Gerrit Code Review will automatically match the commits back to |
| 217 | their original changes by taking advantage of the Change-Id lines. |
| 218 | |
| 219 | If Change-Id lines are not present in the commit messages, consider |
| 220 | amending the message and copying the line from the change's page |
| 221 | on the web, and then using `git push` as described above. |
| 222 | |
| 223 | If Change-Id lines are not available, then the user must use the |
| 224 | manual mapping technique described below. |
| 225 | |
| 226 | For more about Change-Ids, see link:user-changeid.html[Change-Id Lines]. |
| 227 | |
Edwin Kempin | 930187e | 2011-01-27 10:13:42 +0100 | [diff] [blame] | 228 | [[manual_replacement_mapping]] |
Edwin Kempin | b2e42c8 | 2011-01-13 09:29:57 +0100 | [diff] [blame] | 229 | Manual Replacement Mapping |
| 230 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 231 | |
| 232 | .Deprecation Warning |
| 233 | **** |
| 234 | The remainder of this section describes a manual method of replacing |
| 235 | changes by matching each commit name to an existing change number. |
| 236 | End-users should instead prefer to use Change-Id lines in their |
| 237 | commit messages, as the process is then fully automated by Gerrit |
| 238 | during normal uploads. |
| 239 | |
| 240 | See above for the preferred technique of replacing changes. |
| 241 | **** |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 242 | |
| 243 | To add an additional patch set to a change, replacing it with an |
| 244 | updated version of the same logical modification, send the new |
| 245 | commit to the change's ref. For example, to add the commit whose |
| 246 | SHA-1 starts with `c0ffee` as a new patch set for change number |
| 247 | `1979`, use the push refspec `c0ffee:refs/changes/1979` as below: |
| 248 | |
| 249 | ==== |
| 250 | git push ssh://sshusername@hostname:29418/projectname c0ffee:refs/changes/1979 |
| 251 | ==== |
| 252 | |
| 253 | This form can be combined together with `refs/for/'branchname'` |
| 254 | (above) to simultaneously create new changes and replace changes |
| 255 | during one network transaction. |
| 256 | |
| 257 | For example, consider the following sequence of events: |
| 258 | |
| 259 | ==== |
| 260 | $ git commit -m A ; # create 3 commits |
| 261 | $ git commit -m B |
| 262 | $ git commit -m C |
| 263 | |
| 264 | $ git push ... HEAD:refs/for/master ; # upload for review |
| 265 | ... A is 1500 ... |
| 266 | ... B is 1501 ... |
| 267 | ... C is 1502 ... |
| 268 | |
| 269 | $ git rebase -i HEAD~3 ; # edit "A", insert D before B |
| 270 | ; # now series is A'-D-B'-C' |
Shawn O. Pearce | d607846 | 2009-11-02 10:37:01 -0800 | [diff] [blame] | 271 | $ git push ... |
| 272 | HEAD:refs/for/master |
| 273 | HEAD~3:refs/changes/1500 |
| 274 | HEAD~1:refs/changes/1501 |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 275 | HEAD~0:refs/changes/1502 ; # upload replacements |
| 276 | ==== |
| 277 | |
| 278 | At the final step during the push Gerrit will attach A' as a new |
| 279 | patch set on change 1500; B' as a new patch set on change 1501; C' |
| 280 | as a new patch set on 1502; and D will be created as a new change. |
| 281 | |
| 282 | Ensuring D is created as a new change requires passing the refspec |
| 283 | `HEAD:refs/for/branchname`, otherwise Gerrit will ignore D and |
| 284 | won't do anything with it. For this reason it is a good idea to |
| 285 | always include the create change refspec when uploading replacements. |
| 286 | |
| 287 | |
Edwin Kempin | 913eab1 | 2011-05-06 08:18:24 +0200 | [diff] [blame] | 288 | [[bypass_review]] |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 289 | Bypass Review |
| 290 | ~~~~~~~~~~~~~ |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 291 | |
| 292 | Changes (and annotated tags) can be pushed directly into a |
| 293 | repository, bypassing the review process. This is primarily useful |
| 294 | for a project owner to create new branches, create annotated tags |
| 295 | for releases, or to force-update a branch whose history needed to |
| 296 | be rewritten. |
| 297 | |
| 298 | Gerrit restricts direct pushes that bypass review to: |
| 299 | |
| 300 | * `refs/heads/*`: any branch can be updated, created, deleted, |
| 301 | or rewritten by the pusher. |
| 302 | * `refs/tags/*`: annotated tag objects pointing to any other type |
Nico Sallembien | 950e415 | 2010-03-16 15:45:33 -0700 | [diff] [blame] | 303 | of Git object can be created. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 304 | |
Fredrik Luthander | c10f9e7 | 2012-01-23 17:00:45 +0100 | [diff] [blame] | 305 | To push branches, the proper access rights must be configured first. |
| 306 | Here follows a few examples of how to configure this in Gerrit: |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 307 | |
| 308 | * Update: Any existing branch can be fast-forwarded to a new commit. |
| 309 | This is the safest mode as commits cannot be discarded. Creation |
Fredrik Luthander | c10f9e7 | 2012-01-23 17:00:45 +0100 | [diff] [blame] | 310 | of new branches is rejected. Can be configured with |
| 311 | link:access-control.html#category_push_direct['Push'] access. |
| 312 | * Create: Allows creation of a new branch if the name does not |
| 313 | already designate an existing branch name. Needs |
| 314 | link:access-control.html#category_create['Create Reference'] |
| 315 | configured. Please note that once created, this permission doesn't |
| 316 | grant the right to update the branch with further commits (see above |
| 317 | for update details). |
| 318 | * Delete: Implies Update, but also allows an existing |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 319 | branch to be deleted. Since a force push is effectively a delete |
| 320 | followed by a create, but performed atomically on the server and |
| 321 | logged, this also permits forced push updates to branches. |
Fredrik Luthander | c10f9e7 | 2012-01-23 17:00:45 +0100 | [diff] [blame] | 322 | To grant this access, configure |
| 323 | link:access-control.html#category_push_direct['Push'] with the |
| 324 | 'Force' option ticked. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 325 | |
| 326 | To push annotated tags, the `Push Annotated Tag` project right must |
| 327 | be granted to one (or more) of the user's groups. There is only |
| 328 | one level of access in this category. |
| 329 | |
| 330 | Project owners may wish to grant themselves `Push Annotated Tag` |
| 331 | only at times when a new release is being prepared, and otherwise |
| 332 | grant nothing at all. This ensures that accidental pushes don't |
| 333 | make undesired changes to the public repository. |
| 334 | |
| 335 | |
Edwin Kempin | bfa0621 | 2013-04-04 16:06:39 +0200 | [diff] [blame] | 336 | [[auto_merge]] |
| 337 | Auto-Merge during Push |
| 338 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 339 | |
| 340 | Changes can be directly submitted on push. This is primarily useful |
| 341 | for teams that don't want to do code review but want to use Gerrit's |
| 342 | submit strategies to handle contention on busy branches. Using |
| 343 | `%submit` creates a change and submits it immediately, if the caller |
| 344 | has link:access-control.html#category_submit[Submit] permission on |
| 345 | `refs/for/<ref>` (e.g. on `refs/for/refs/heads/master`). |
| 346 | |
| 347 | ==== |
| 348 | git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%submit |
| 349 | ==== |
| 350 | |
| 351 | On auto-merge of a change neither labels nor submit rules are checked. |
| 352 | If the merge fails the change stays open, but when pushing a new patch |
| 353 | set the merge can be reattempted by using `%submit` again. |
| 354 | |
| 355 | |
Shawn Pearce | 5d8a290 | 2013-04-22 11:50:23 -0700 | [diff] [blame] | 356 | [[base]] |
| 357 | Selecting Merge Base |
| 358 | ~~~~~~~~~~~~~~~~~~~~ |
| 359 | |
| 360 | By default new changes are opened only for new unique commits |
| 361 | that have never before been seen by the Gerrit server. Clients |
| 362 | may override that behavior and force new changes to be created |
| 363 | by setting the merge base SHA-1 using the '%base' argument: |
| 364 | |
| 365 | ==== |
| 366 | git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%base=$(git rev-parse origin/master) |
| 367 | ==== |
| 368 | |
| 369 | |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 370 | repo upload |
| 371 | ----------- |
| 372 | |
| 373 | repo is a multiple repository management tool, most commonly |
| 374 | used by the Android Open Source Project. For more details, see |
Orgad Shaneh | c9e11de | 2012-12-24 16:49:09 +0200 | [diff] [blame] | 375 | link:http://source.android.com/source/using-repo.html[using repo]. |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 376 | |
| 377 | [[repo_create]] |
| 378 | Create Changes |
| 379 | ~~~~~~~~~~~~~~ |
| 380 | |
| 381 | To upload changes to a project using `repo`, ensure the manifest's |
| 382 | review field has been configured to point to the Gerrit server. |
| 383 | Only the hostname or the web address needs to be given in the |
| 384 | manifest file. During upload `repo` will automatically determine the |
| 385 | correct port number by reading `http://'reviewhostname'/ssh_info` |
| 386 | when its invoked. |
| 387 | |
| 388 | Each new commit uploaded by `repo upload` will be converted into |
| 389 | a change record on the server. Other users (e.g. project owners) |
| 390 | who have configured Gerrit to notify them of new changes will be |
| 391 | automatically sent an email message. Additional notifications can |
| 392 | be sent through command line options. |
| 393 | |
| 394 | For more details on using `repo upload`, see `repo help upload`. |
| 395 | |
| 396 | [[repo_replace]] |
| 397 | Replace Changes |
| 398 | ~~~~~~~~~~~~~~~ |
| 399 | |
| 400 | To replace changes, ensure Change-Id lines were created in the |
Cecilia Svensson | cd2491d | 2012-01-20 14:22:30 +0100 | [diff] [blame] | 401 | commit messages, and just use `repo upload`. |
| 402 | Gerrit Code Review will automatically match the commits back to |
| 403 | their original changes by taking advantage of their Change-Id lines. |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 404 | |
| 405 | If Change-Id lines are not present in the commit messages, consider |
| 406 | amending the message and copying the line from the change's page |
| 407 | on the web. |
| 408 | |
| 409 | If Change-Id lines are not available, then the user must use the much |
Cecilia Svensson | cd2491d | 2012-01-20 14:22:30 +0100 | [diff] [blame] | 410 | more <<manual_replacement_mapping,manual mapping technique>> offered |
| 411 | by using `git push` to a specific `refs/changes/change#` reference. |
Shawn O. Pearce | 518fe3f | 2009-08-22 15:40:58 -0700 | [diff] [blame] | 412 | |
| 413 | For more about Change-Ids, see link:user-changeid.html[Change-Id Lines]. |
| 414 | |
| 415 | |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 416 | Gritty Details |
| 417 | -------------- |
| 418 | |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 419 | As Gerrit implements the entire SSH and Git server stack within its |
| 420 | own process space, Gerrit maintains complete control over how the |
| 421 | repository is updated, and what responses are sent to the `git push` |
| 422 | client invoked by the end-user, or by `repo upload`. This allows |
Edwin Kempin | cdb0e00 | 2011-09-08 14:23:30 +0200 | [diff] [blame] | 423 | Gerrit to provide magical refs, such as `refs/for/*` for new |
| 424 | change submission and `refs/changes/*` for change replacement. |
Shawn O. Pearce | e61a3c6 | 2009-01-29 08:42:41 -0800 | [diff] [blame] | 425 | When a push request is received to create a ref in one of these |
| 426 | namespaces Gerrit performs its own logic to update the database, |
| 427 | and then lies to the client about the result of the operation. |
| 428 | A successful result causes the client to believe that Gerrit has |
| 429 | created the ref, but in reality Gerrit hasn't created the ref at all. |
| 430 | |
| 431 | By implementing the entire server stack, Gerrit is also able to |
| 432 | perform project level access control checks (to verify the end-user |
| 433 | is permitted to access a project) prior to advertising the available |
| 434 | refs, and potentially leaking information to a snooping client. |
| 435 | Clients cannot tell the difference between 'project not found' and |
| 436 | 'project exists, but access is denied'. |
| 437 | |
| 438 | Gerrit can also ensure users have completed a valid Contributor |
| 439 | Agreement prior to accepting any transferred objects, and if an |
| 440 | agreement is required, but not completed, it aborts the network |
| 441 | connection before data is sent. This ensures that project owners |
| 442 | can be certain any object available in their repository has been |
| 443 | supplied under at least one valid agreement. |
Shawn O. Pearce | 5500e69 | 2009-05-28 15:55:01 -0700 | [diff] [blame] | 444 | |
| 445 | GERRIT |
| 446 | ------ |
| 447 | Part of link:index.html[Gerrit Code Review] |