| Gerrit Code Review - Change-Ids | |
| =============================== | |
| Description | |
| ----------- | |
| Gerrit Code Review sometimes relies upon Change-Id lines in the | |
| bottom of a commit message to uniquely identify a change across all | |
| drafts of it. By including a unique Change-Id in the commit message, | |
| Gerrit can automatically associate a new version of a change back | |
| to its original review, even across cherry-picks and rebases. | |
| To be picked up by Gerrit, a Change-Id line must be in the bottom | |
| portion (last paragraph) of a commit message, and may be mixed | |
| together with the Signed-off-by, Acked-by, or other such footers. | |
| For example: | |
| ---- | |
| $ git log -1 | |
| commit 29a6bb1a059aef021ac39d342499191278518d1d | |
| Author: A. U. Thor <author@example.com> | |
| Date: Thu Aug 20 12:46:50 2009 -0700 | |
| Improve foo widget by attaching a bar. | |
| We want a bar, because it improves the foo by providing more | |
| wizbangery to the dowhatimeanery. | |
| Bug: #42 | |
| Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b | |
| Signed-off-by: A. U. Thor <author@example.com> | |
| CC: R. E. Viewer <reviewer@example.com> | |
| ---- | |
| In the above example, `Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b` | |
| is the unique identity assigned to this change. It does not match | |
| the commit name, `29a6...`, as the change may have been amended or | |
| rebased to address reviewer comments since its initial inception. | |
| To avoid confusion with commit names, Change-Ids typically are with | |
| an uppercase `I`. | |
| Creation | |
| -------- | |
| Gerrit Code Review provides a standard 'commit-msg' hook which | |
| can be installed in the local Git repository to automatically | |
| create and insert a unique Change-Id line during `git commit`. | |
| To install the hook, copy it from Gerrit's daemon: | |
| $ scp -p -P 29418 review.example.com:hooks/commit-msg .git/hooks/ | |
| $ curl http://review.example.com/tools/hooks/commit-msg | |
| For more details, see link:cmd-hook-commit-msg.html[commit-msg]. | |
| Change Upload | |
| -------------- | |
| During upload by pushing to a `refs/for/\*` or `refs/heads/\*` | |
| branch, Gerrit will use the Change-Id line to: | |
| * Create a new change | |
| + | |
| If this is the first time it has seen the Change-Id mentioned in | |
| the commit message, Gerrit will create a new change for review. | |
| * Update an existing change | |
| + | |
| If Gerrit has seen this Change-Id before, but has not yet seen this | |
| new commit object, Gerrit will add the new commit as a new patch | |
| set on the existing change. | |
| * Close an existing change | |
| + | |
| If Gerrit has seen this Change-Id before, and the commit is being | |
| pushed directly into a branch, the existing change is updated with | |
| the new commit, and the change is closed and marked as merged. | |
| If a Change-Id line is not present in the commit message, Gerrit will | |
| automatically generate its own Change-Id and display it on the web. | |
| This line can be manually copied and inserted into an updated commit | |
| message if additional revisions to a change are required. | |
| For more details on using git push to upload changes to Gerrit, | |
| see link:user-upload.html#push_create[creating changes by git push]. | |
| Git Tasks | |
| --------- | |
| [[new]] | |
| Creating a new commit | |
| ~~~~~~~~~~~~~~~~~~~~~ | |
| When creating a new commit, ensure the 'commit-msg' hook has been | |
| installed in your repository (see above), and don't put a Change-Id | |
| line in the commit message. When you exit the editor, git will call | |
| the hook, which will automatically generate and insert a unique | |
| Change-Id line. You can inspect the modified message after the | |
| commit is complete by executing `git show`. | |
| [[amend]] | |
| Amending a commit | |
| ~~~~~~~~~~~~~~~~~ | |
| When amending a commit with `git commit \--amend`, leave the | |
| Change-Id line unmodified in the commit message. This will allow | |
| Gerrit to automatically update the change with the amended commit. | |
| [[rebase]] | |
| Rebasing a commit | |
| ~~~~~~~~~~~~~~~~~ | |
| When rebasing a commit, leave the Change-Id line unmodified in the | |
| commit message. This will allow Gerrit to automatically update | |
| the change with the rebased commit. | |
| [[squash]] | |
| Squashing commits | |
| ~~~~~~~~~~~~~~~~~ | |
| When squashing several commits together, try to preserve only one | |
| Change-Id line, and remove the others from the commit message. | |
| When faced with multiple lines, try to preserve a line which was | |
| already uploaded to Gerrit Code Review, and thus has a corresponding | |
| change that reviewers have already examined and left comments on. | |
| If you aren't sure which lines Gerrit knows about, try copying and | |
| pasting the lines into the search box in the top-right. | |
| If Gerrit already knows about more than one Change-Id, pick one | |
| to keep in the squashed commit message, and manually abandon the | |
| other changes through the web interface. | |
| [[cherry-pick]] | |
| Cherry-picking a commit | |
| ~~~~~~~~~~~~~~~~~~~~~~~ | |
| When cherry-picking a commit, leave the Change-Id line alone to | |
| have Gerrit treat the cherry-picked commit as a replacement for | |
| the existing change. This can be very useful if the project has | |
| a fast-forward-only merge policy, and the submitter is downloading | |
| and cherry-picking individual changes prior to submission, such as | |
| by link:cmd-cherry-pick.html[gerrit-cherry-pick]. | |
| Or, you may wish to delete the Change-Id line and force a new | |
| Change-Id to be generated automatically, thus creating an entirely | |
| new change record for review. This may be useful when backporting | |
| a change from the current development branch to a maintenance | |
| release branch. | |
| [[update-old]] | |
| Updating an old commit | |
| ~~~~~~~~~~~~~~~~~~~~~~ | |
| If a commit was created before the availability of Change-Id support, | |
| or was created in a Git repository that was missing the 'commit-msg' | |
| hook, simply copy the "`Change-Id: I...`" line from the first line | |
| of the Description section of the change and amend it to the bottom | |
| of the commit message. Any subsequent uploads of the commit will | |
| be automatically associated with the prior change. | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] |