Working with Gerrit as a Developer

How you work from this point onwards depends on how you intend making your code available to us. We're still happy to receive submission by patch (attach the patch to the issue you created or worked on using the Forge), but it makes it much easier for us if you push directly from your git tree to our code review system, gerrit.

Uploading to gerrit

Pushing to gerrit

When submitting to gerrit, it's important to realise that each commit in your branch will become a changeset in the upstream codebase, typically with no modification at our end. It is therefore important that these commits follow some simple rules...

Each commit should be complete. The rule "one change per commit, one commit per change" applies here. Each commit should build and test in its own right. If, during development, you have created multiple commits for a change (for example, you've created a large number of bug fix commits), please use 'git rebase', or cherry pick these commits into a separate tree before uploading them.

Each commit should have a meaningful revision log message. We can't easily edit these before pushing them into the tree, so we'd like you to get them right for us! Here are the FLOW3 commit message rules for Git, explaining in detail this example:

[TASK] Fix the foobar problem when using baz

The foobar was not corrently fumbled when using baz, now this works as 

Resolves: #345
Related: #789

Once you have commits in this form, use

git log -p origin/<branch>..HEAD
(where <branch> is the upstream branch upon which you are basing this patch) to check that what you're giving us makes sense.

Make sure the Change-Id line is in the commit message(s), if it is not, check the commit-msg hook and amend the commit to get the Change-Id in.

Be nitpicky and precise, please! Better safe than sorry!

Then, upload them to gerrit using

git push ssh://<projectname> HEAD:refs/for/<branch>

(again <branch> is the name of the upstream branch that you are pushing the changes into, not the name of any local branch you may have been developing on).

In this case, 'refs/for' is a literal string. So, if you had been developing against master, you can upload your changes with:

git push ssh://<projectname> HEAD:refs/for/master

This relies upon the ssh configuration you performed earlier. If it fails to work, please consult the gerrit troubleshooting notes

Assuming all has gone well, this will have added the entry to the code review queue. The output from git review will give you a change number - this is a unique reference for this particular set of changes. During review you'll be emailed with any comments anyone makes, and can respond to those comments using the gerrit web interface (see the section on reviewing, below). It's possible that issues with your change may be noticed during the review process, and you may be asked to revise it, or update changes to the tip of the tree.

To make life easier, you can add the review server and the needed refspec to your clone's .git/config file like this:

git config remote.origin.push HEAD:refs/for/master
git config remote.origin.pushurl ssh://<projectname>

This will create a configuration like this:
[remote "origin"]
  fetch = +refs/heads/*:refs/remotes/origin/*
  url = git://<projectname>.git
  pushurl = ssh://<projectname>
  push = HEAD:refs/for/master

Then you can use a simple
git push

to submit a change to gerrit.

Depending on your setup it may help to include username and port in the pushurl to be picked up by some tools (like SmartGit).

Revising your change

It's possible that your modifications won't be accepted first time. In this case, you need to revise your changes, and resubmit them to gerrit. Please note that this should always be done by modifying your original changeset, not by submitting a new change that makes the required fixes.

If you use topic branches, switch to the according branch. If you no longer have the branch or didn't use a topic branch, you can check out the needed state using the information shown for the change in gerrit.

After you fixed your change, either git commit --amend, or git rebase should be used to combine your changes with the original changeset, and then you should push this to gerrit like you did before:

git push ssh://<projectname> HEAD:refs/for/<branch>

The Change-Id lines in the commit message will be used to match the commit to the existing review entry.

If no Change-Id was present in the entry, things get more complicated. 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 0ffee:refs/changes/1979 as below:

git push ssh://<projectname> c0ffee:refs/changes/1979
You can obtain the sha1 hash of a commit by using 'git show' (if it is on the tip of your current branch), or 'git log' (if it is in your history). This method is considered deprecated in favour of Change-Id lines!

Make sure to read the documentation on uploading changes for details.

Updating your change

It's possible that your change may have been made against a tree which is too old for it to apply to the tip. In this case, gerrit will let you know that there is a collision, and request that you update the change to the tip.

You can do this with

git rebase origin/master <topic>

(assuming your patch is against the 'master' git branch, and lives on the <topic> branch).

And then simply resubmit your change in the same way as if you had been asked to revise it (see notes above)

Submitting by patch

If all of this seems too daunting (and please don't let it put you off) you can still, of course, submit patches by email.

git diff HEAD

will give you the set of changes if you don't do local commits. If you make topic branches, and commit things locally, but don't want to go through the whole gerrit process,
git diff master..<topic>

will give all of the changes between the branch point of you topic branch (assuming you branched from 'master') and the last commit.
You can attach those to issues in the Forge issue trackers as before. Note, however, by doing this you're making someone else take the patch, create a topic branch in their local tree, apply the patch, and push it into gerrit.

Things would be much more efficient if you pushed into gerrit yourself. Please?

Committing Patches

Patches sent in or attached to the issue tracker still need to be committed and pushed by someone. To commit a patch, make a new topic branch, and apply the patch to that branch. When committing, use

git commit --author="A.N. Author <>"

to acknowledge the patch author (your name will still be there as the committer of the patch). Push the patch into gerrit as usual, and wait for reviews ...

Updated by Irene Höppner over 9 years ago · 12 revisions