2 title: Gerrit Recommended Practices
5 This document presents some best practices to help you use Gerrit more
6 effectively. The intent is to show how content can be submitted easily.
7 Use the recommended practices to reduce your troubleshooting time and
8 improve participation in the community.
12 Gerrit follows the Git commit message format. Ensure the headers are at
13 the bottom and don't contain blank lines between one another. The
14 following example shows the format and content expected in a commit
17 Brief (no more than 50 chars) one line description.
19 Elaborate summary of the changes made referencing why (motivation), what
20 was changed and how it was tested. Note also any changes to
21 documentation made to remain consistent with the code changes, wrapping
22 text at 72 chars/line.
25 Bug-AGL: SPEC-<JIRA-ID>
27 Change-Id: LONGHEXHASH
28 Signed-off-by: Your Name your.email\@example.org
31 The Gerrit server provides a precommit hook to autogenerate the
32 Change-Id which is one time use.
34 **Recommended reading:** [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
36 ## Avoid Pushing Untested Work to a Gerrit Server
38 To avoid pushing untested work to Gerrit.
40 Check your work at least three times before pushing your change to
41 Gerrit. Be mindful of what information you are publishing.
43 ## Keeping Track of Changes
45 - Set Gerrit to send you emails:
47 - Gerrit will add you to the email distribution list for a change if a
48 developer adds you as a reviewer, or if you comment on a specific
51 - Opening a change in Gerrit's review interface is a quick way to
54 - Watch projects in the Gerrit projects section at ``Gerrit``, select
55 at least *New Changes, New Patch Sets, All Comments* and *Submitted
58 Always track the projects you are working on; also see the
59 feedback/comments [mailing list](https://lists.automotivelinux.org/g/agl-dev-community)
60 to learn and help others ramp up.
64 Topic branches are temporary branches that you push to commit a set of
65 logically-grouped dependent commits:
67 To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed
68 as a topic in **TopicName** use the following command as an example:
71 $ git push REMOTE HEAD:refs/for/master/TopicName
74 The topic will show up in the review ``UI`` and in the
75 ``Open Changes List``. Topic branches will disappear from the master
76 tree when its content is merged.
78 ## Finding Available Topics
81 $ ssh -p 29418 <LFID>@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u
84 - [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the current URL where the project is hosted.
85 - *status* : Indicates the topic's current status: open , merged,
86 abandoned, draft, merge conflict.
87 - *project* : Refers to the current name of the project, in this case
89 - *branch* : The topic is searched at this branch.
90 - *topic* : The name of an specific topic, leave it blank to include them
92 - *sort* : Sorts the found topics, in this case by update (-u).
94 ## Downloading or Checking Out a Change
96 In the review UI, on the top right corner, the **Download** link
97 provides a list of commands and hyperlinks to checkout or download diffs
100 We recommend the use of the *git review* plugin. The steps to install
101 git review are beyond the scope of this document. Refer to the
102 [git review documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers)
103 for the installation process.
105 To check out a specific change using Git, the following command usually
109 $ git review -d CHANGEID
112 If you don't have Git-review installed, the following commands will do
116 $ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD
119 For example, for the 4th version of change 2464, NN is the first two
123 $ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD
126 ## Using Sandbox Branches
128 You can create your own branches to develop features. The branches are
129 pushed to the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location.
131 These commands ensure the branch is created in Gerrit's server.
134 $ git checkout -b sandbox/USERNAME/BRANCHNAME
135 $ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME
138 Usually, the process to create content is:
141 - break the information into small commits,
146 The next command pushes forcibly without review:
149 $ git push REMOTE sandbox/USERNAME/BRANCHNAME
152 You can also push forcibly with review:
155 $ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME
158 ## Updating the Version of a Change
160 During the review process, you might be asked to update your change. It
161 is possible to submit multiple versions of the same change. Each version
162 of the change is called a patch set.
164 Always maintain the **Change-Id** that was assigned. For example, there
165 is a list of commits, **c0...c7**, which were submitted as a topic
170 $ git log REMOTE/master..master
176 $ git push REMOTE HEAD:refs/for/master/SOMETOPIC
179 After you get reviewers' feedback, there are changes in **c3** and
180 **c4** that must be fixed. If the fix requires rebasing, rebasing
181 changes the commit Ids, see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section for more information. However, you must keep the same Change-Id
182 and push the changes again:
185 $ git push REMOTE HEAD:refs/for/master/SOMETOPIC
188 This new push creates a patches revision, your local history is then
189 cleared. However you can still access the history of your changes in
190 Gerrit on the ``review UI`` section, for each change.
192 It is also permitted to add more commits when pushing new versions.
196 Rebasing is usually the last step before pushing changes to Gerrit; this
197 allows you to make the necessary *Change-Ids*. The *Change-Ids* must be
200 - **squash:** mixes two or more commits into a single one.
201 - **reword:** changes the commit message.
202 - **edit:** changes the commit content.
203 - **reorder:** allows you to interchange the order of the commits.
204 - **rebase:** stacks the commits on top of the master.
206 ## Rebasing During a Pull
208 Before pushing a rebase to your master, ensure that the history has a
211 For example, your ``REMOTE/master`` has the list of commits from **a0**
212 to **a4**; Then, your changes **c0...c7** are on top of **a4**; thus:
215 $ git log --oneline REMOTE/master..master
228 If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull
229 with a rebase as follows:
232 $ git pull --rebase REMOTE master
235 This pulls **a5-a7** and re-apply **c0-c7** on top of them:
238 $ git log --oneline REMOTE/master..master
248 ## Getting Better Logs from Git
250 Use these commands to change the configuration of Git in order to
254 $ git config log.abbrevCommit true
257 The command above sets the log to abbreviate the commits' hash.
260 $ git config log.abbrev 5
263 The command above sets the abbreviation length to the last 5 characters
267 $ git config format.pretty oneline
270 The command above avoids the insertion of an unnecessary line before the