Cloning from Gerrit

While access to the underlying git repository is open to anyone via anonymous HTTP access, this guide will assume that you want to push changes up as well. For that, Gerrit uses SSH. If you are only looking to obtain the source code for a particular repository, you may just use the HTTP methods shown below.

1. Clone the repository:
   

   1. SSH:

      Code Block
      $ git clone ssh://{user}@gerrit.asterisk.org:29418/{repo}

   2. HTTP:

      Code Block
      $ git clone https://{user}@gerrit.asterisk.org/{repo}

   3. Anonymous HTTP:

      Code Block
      $ git clone http://gerrit.asterisk.org/{repo}

2. Copy the commit-msg hook into your local .git/hooks folder:

   1. If you have git-review installed:

      Code Block
      $ git review -s

   2. Otherwise:

      Code Block
      $ scp -p -P 29418 {user}@gerrit.asterisk.org:hooks/commit-msg {local-repo}/.git/hooks/

      The commit-msg hook adds the Change-Id automatically to git commit messages. A Change-Id is necessary for Gerrit to associate multiple patch sets together. For more information, see Change-Ids.

Creating an SSH Alias

Since access to gerrit.asterisk.org is likely to occur often, you may want to set up an SSH alias:

$ cat ~/.ssh/config
...
Host asterisk
  Hostname gerrit.asterisk.org
  Port 29418
  User {user}

This will allow you to access the repository as shown below:

$ git clone asterisk:{repo}

Pushing to Gerrit for Code Review

Anchor
git-review git-review

Use git review

1. Install git-review:

   Code Block
   $ pip install git-review

2. To submit a change to master as a draft:

   Code Block
   $ git review -D

3. To submit a change to master:

   Code Block
   $ git review

   Note that this will automatically publish the change to the asterisk-dev mailing list!
   
   

4. To submit a change for a particular branch:

   Code Block
   $ git review {branchname}

5. To submit a change, including the ASTERISK issue:

   Code Block
   $ git review -t ASTERISK-12345

Use git push

Pushing to Gerrit for code review can always be done using standard git commands. This is done by pushing to the refs/for/[branch]. Generally, this will be master, unless pushing to a particular mainline Asterisk branch.

$ git push asterisk:{repo} HEAD:refs/for/master

Updating a Review

1. Reviews are automatically updated so long as commits contain the same Change ID. If your review has any findings, rebase the commits as appropriate, making sure the Change ID is preserved:

   Code Block
   $ git rebase -i

2. Re-push the changes:

   Code Block
   $ git review

   or:

   Code Block
   $ git push asterisk:{repo} HEAD:refs/for/master

Branch Cherry-Picking

Patches being submitted to the project must be cherry-picked to other branches when either:

• The patch is a bug fix. In this case, the patch should be cherry-picked to all supported branches that have the bug.

• The patch is a new feature or improvement, and tests have been written to cover the new feature or improvement. In that case, the patch may be submitted to other supported branches.

  Note
  Not all changes are appropriate for all branches. See Software Configuration Management Policies for more information. If you have questions about whether or not a change is appropriate for a particular branch, feel free to ask on the asterisk-dev mailing list or in #asterisk-dev.

Cherry-picking can be done either when a patch is first proposed, or it may be done when the patch has been reviewed but prior to it being submitted. If you plan on cherry-picking after an initial review, please indicate so in a comment on the review.

Cherry-Picking in Gerrit

If your patch applies cleanly to a branch, you can cherry-pick directly in Gerrit. On your review, select the Cherry-Pick button:

In the resulting dialog, enter the branch you want to cherry-pick to, then select Cherry Pick Change.

If the change merges cleanly, a new review will be opened with your cherry-picked change. If the change could not be merged, and error will appear and you will need to use one of the manual methods listed below.

Cherry-Picking using git review

If you have already submitted a patch for review, you may cherry pick to a new branch using git review:

#$ git review --cherrypick {review id} {origin branch}

As an example, if we previously posted for review a code change for Asterisk 11, and the Gerrit Review ID is 30, we might use the following for Asterisk 13:

#$ git review --cherrypick 30 13

Cherry-Picking using git cherry-pick

You may cherry pick using git cherry-pick as well. When performing the cherry-pick using git, make sure that the Change-Id header is the same between all branches.

As an example, if we committed the following to Asterisk 13:

commit dc8f87145c352c1bcf1a3361802aac26da5f50e2
Refs: review/asteriskteam/file-version-13, file-version-13
Author:     Asterisk Development Team <[email protected]>
AuthorDate: Sun Apr 12 12:59:22 2015 -0500
Commit:     Asterisk Development Team <[email protected]>
CommitDate: Sun Apr 12 20:20:19 2015 -0500

    git migration: Remove support for file versions

    Git does not support the ability to replace a token with a version
    string during check-in. While it does have support for replacing a
    token on clone, this is somewhat sub-optimal: the token is replaced
    with the object hash, which is not particularly easy for human
    consumption. What's more, in practice, the source file version was often
    not terribly useful. Generally, when triaging bugs, the overall version
    of Asterisk is far more useful than an individual SVN version of a file.
    As a result, this patch removes Asterisk's support for showing source file
    versions.

	ASTERISK-12345

    Change-Id: Ia932d3c64cd18a14a3c894109baa657ec0a85d28

We could then cherry pick this back to Asterisk 11 using the following:

$ git cherry-pick dc8f87145c352c1bcf1a3361802aac26da5f50e2

The resulting commit must have the same Change-Id as the Asterisk 13 commit for Gerrit to recognize that this is a cherry-picked commit:

    Change-Id: Ia932d3c64cd18a14a3c894109baa657ec0a85d28

When posting it for review to Gerrit, you should also use the same topic as the original patch. Generally, this is the ASTERISK issue.

$ git review -t ASTERISK-12345 11

Team Branches

The repositories on Gerrit typically require all changes in all of the mainline branches to be reviewed prior to merging. While this is appropriate for the mainline branches, sometimes, it is useful to have a branch on the central server that multiple developers can use for collaboration. These branches exist within a special branch namespace, team. Registered Gerrit users have the ability to manipulate branches within that namespace directly, bypassing the usual Gerrit code review process.

Team Branch Manipulation in Gerrit

Creating a new Team Branch

Creating a new team branch can be done at any time from a local branch. For example, to create a new team branch from local master:

#$ git push origin master:refs/heads/team/mjordan/awesome-feature

 Check out a Team Branch

Checking out a team branch is done in the same way as a mainline branch:

#$ git checkout -b awesome-feature -t origin/team/mjordan/awesome-feature

Pushing to a Team Branch

Pushing to a team branch can be done directly. This bypasses Gerrit's peer review. Note that team branches can be peer reviewed if desired, using the same mechanism as a 'normal' Gerrit peer review.

#$ git push origin HEAD:refs/heads/team/mjordan/awesome-feature

Delete a Team Branch

Deleting a team branch is done by pushing an empty local branch (nothing) to the team branch. Note that you have to use git push --force.

#$ git push --force origin :refs/heads/team/mjordan/awesome-feature

Recovering a Subversion Team Branch

While the Subversion Team branches were moved over to Git with their entire history, much of that history typically consists of Automerge commits. These commits are not well understood by Git; from Git's perspective, they are completely independent from the mainline commits they merged over. This can cause a "standard" rebase to fail miserably: the rebase will not realize that the Automerge commits are identical to those on the branch being rebased to. As a result, you'll often have a lot of merge conflicts if you attempt to rebase directly.

While working through the merge conflicts in a rebase is an option, an easier approach may be to simply re-build the branch on the current state of the mainline branch it wants to track. This example walks through that process, performing a rebase of branch team/mjordan/trunk-http-stuff-and-things on top of master.

1. Checkout the subversion team history branch into a temporary local branch:

   Code Block
   #$ git checkout -b http-caching-temp -t origin/team/mjordan/trunk-http-stuff-and-things

2. Determine the useful commits to pull over. In this case, we're going to skip:
   1. All commits from Automerge script.
   2. All commits that modify Subversion properties or create Subversion branches.
      
      In the above screenshot, we want the three commits from Matthew Jordan between the Automerge: script automerge cancel and the Matthew Jordan: Re-enable automerge.
   3. Record the hashes of the commits you want to carry-over.

3. Checkout a new branch for your work, tracking whatever canonical mainstream branch is appropriate:

   Code Block
   #$ git checkout -b http-caching -t origin/master

4. Cherry-pick each commit over, solving merge conflicts as necessary:

   Code Block
   #$ git cherry-pick 5037821233a366f4afae83c732eb318e64bdb6f5 #$ git cherry-pick 9905eaad7a8c8a13363ae4129d7d483c8559cb7a #$ git cherry-pick 32fe36b0e14f8c072c2bfea9443a946cfe3628d6 #$ git cherry-pick a5eb0d4b178eee070047549d635ada8d562c3d73

5. If desired, fix up any history:

   Code Block
   #$ git rebase -i

6. Remove the temporary branch:

   Code Block
   #$ git branch -d

   Tip
   You may get the following warning: Code Block warning: deleting branch 'http-caching-temp' that has been merged to 'refs/remotes/origin/team/mjordan/trunk-http-stuff-and-things', but not yet merged to HEAD. Deleted branch http-caching-temp (was 9c6910d). That's okay. You don't want to merge the whole thing to HEAD, as the Automerge script commits are duplicates of commits already in HEAD.

7. Push the branch up to your team branch location:

   Code Block
   #$ git push origin HEAD:refs/heads/team/mjordan/http-caching

   Tip
   In this example, a new team branch is being made - team/mjordan/http-caching. This way, if something is missed in the cherry-picks, I haven't blown away my Subversion branch.

Troubleshooting

git-review

Problem: attempting to run git review results in something like the following:

Traceback (most recent call last):
  File "/usr/local/bin/git-review", line 11, in <module>
    sys.exit(main())
  File "/usr/local/lib/python2.6/dist-packages/git_review/cmd.py", line 1132, in main
    (os.path.split(sys.argv[0])[-1], get_version()))
  File "/usr/local/lib/python2.6/dist-packages/git_review/cmd.py", line 180, in get_version
    provider = pkg_resources.get_provider(requirement)
  File "/usr/lib/python2.6/dist-packages/pkg_resources.py", line 176, in get_provider
    return working_set.find(moduleOrReq) or require(str(moduleOrReq))[0]
  File "/usr/lib/python2.6/dist-packages/pkg_resources.py", line 648, in require
    needed = self.resolve(parse_requirements(requirements))
  File "/usr/lib/python2.6/dist-packages/pkg_resources.py", line 546, in resolve
    raise DistributionNotFound(req)
pkg_resources.DistributionNotFound: git-review

Solution: Run

$ sudo pip install --upgrade setuptools

on your command line

Problem: attempting to run git review results in "unpack failed: error Missing tree":

Description:  There is an incompatibility between certain version of git and gerrit that causes this error when the commit to be pushed was amended and only the commit message changed.
Solution:  Run git push manually with the --no-thin option:

$ git push --no-thin asterisk:{repo} HEAD:refs/for/master