This primer is to aid the ITK developer community in using Gerrit. Some of the idiosyncrasies of Gerrit take a little work to understand and appreciate, especially if one is new to using the git distributed revision control system.
- 1 Gerrit basics
- 2 git / Gerrit workflow
Gerrit is designed to take a single change with a change log and make it publicly available for comments and revisions. Once the change has been sufficiently reviewed and approved, it will be pushed into the official ITK repository. Gerrit addresses the problem of many changes scattered about many git repositories by bringing them into a central place and allowing commenting and changes to become transparent to the rest of the community.
Creating a Gerrit account
To register with Gerrit, first have your OpenID ready. Then visit http://review.source.kitware.com/. Click the "Register" link in the upper left. If you have a Google or Yahoo account, click on the "Register with a Google account". This will create your account. Otherwise, enter the URL of an OpenID provider.
git / Gerrit workflow
For the sake of this primer, we'll be making a series of small documentation changes to ITK code. The basic workflow from the developer's standpoint is:
- Clone the ITK official repository
- Create a topic branch
- Edit, commit, edit, commit, ad infinitum
- Compress your branch into a single commit
- Push your changes into Gerrit
- Stage changes into the ITK official repository
These steps will be detailed in the next sections.
Clone the ITK official repository
The instructions for cloning the official repository are here. For the minimalist:
git clone git://itk.org/ITK.git cd ITK
Create a topic branch
git works well to create "micro-branches". Frequently, branches are considered poor practice in centralized revision control systems such as CVS and Subversion. However, in git branches are typically very easy to work with and manipulate. They are required for working with Gerrit, so get used to them.
We'll call our branch GerritPrimer. The branch may be created it two steps:
git branch GerritPrimer # Create a new branch from our existing revision git checkout GerritPrimer # Switch our working directory into the GerritPrimer branch
or you can do this all at once:
git checkout -b GerritPrimer # Create GerritPrimer and switch the working directory into that revision
When we are finished, our revision history looks like this:
Notice that GerritPrimer, master, origin/HEAD and origin/master branches all point to the same commit. You can think of branches is movable labels that point to a particular commit in the revision history. As we add code and commit our changes, we'll see GerritPrimer move.
Edit, commit, edit, commit, ad infinitum
Next, we'll edit some files and commit the changes. In this primer, we'll make 3 changes.
Edit ITK/Code/BasicFilters/itkRecursiveGaussianImageFilter.h add " * \see DiscreteGaussianImageFilter" on line 54
Next we ask git to show us what's happening:
revelation:ITK(GerritPrimer) blezek$ git status # On branch GerritPrimer # Changed but not updated: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: Code/BasicFilters/itkRecursiveGaussianImageFilter.h # no changes added to commit (use "git add" and/or "git commit -a")
git has the concept of an index, or an area where changes are stored before they are committed. In the listing above, git knows that Code/BasicFilters/itkRecursiveGaussianImageFilter.h is changed, but it has not yet staged that change into the index. To tell git that we want to add this change into the next commit, and make the commit we can do this in two steps:
git add Code/BasicFilters/itkRecursiveGaussianImageFilter.h # Add the modified code into the index git commit # commit all modifications
or in one step:
git commit -a # Auto-add all modified files into the index, then commit all modifications
After two more commits, our repository looks like this:
From where we made the branch (master, origin/HEAD, origin/master), we have three commits. Notice that the GerritPrimer tag has moved along with our commits.
Compress your branch into a single commit
Gerrit expects only a single commit. If we were to push our branch to Gerrit, it would show up as 3 independent commits for commenting / approvals. So we need to collapse our three commits into a single commit. This is easily accomplished using the git rebase command. What we are going to ask git to do is create one commit from the three that we currently have. The command is:
git rebase -i HEAD~3
The -i flag instructs rebase to do this interactively, and "HEAD~3" tells git to collapse the last three commits. We can also use:
git rebase -i master
because right now, master and HEAD~3 point to the same commit. We can also use the SHA1 of that particular commit.
When we run the command we get this:
pick 1e01adb Added documentation. pick b465a05 Documentation changes. pick 7d7f3c1 Documentation changes. # Rebase 43b5f37..7d7f3c1 onto 43b5f37 # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # # If you remove a line here THAT COMMIT WILL BE LOST. # However, if you remove everything, the rebase will be aborted. #
We see three lines at the top which contain the first lines from our three commits. We need to change this commit message to tell git rebase what we want to do. What we would like to do is pick the first commit, and squash the other two. The end result will be a single commit. The file looks like this when we are done:
pick 1e01adb Added documentation. squash b465a05 Documentation changes. squash 7d7f3c1 Documentation changes. ...
git processes what we've done and puts us back into editing the commit message:
# This is a combination of 3 commits. # The first commit's message is: Added documentation. Added \sa tag to reference DiscreteGaussianImageFilter. # This is the 2nd commit message: Documentation changes. Added \sa tag to reference RecursiveGaussianImageFilter. # This is the 3rd commit message: Documentation changes. Added \sa tag to reference Recursive and Discrete GaussianImageFilters. # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # Not currently on any branch. # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: Code/BasicFilters/itkBilateralImageFilter.h # modified: Code/BasicFilters/itkDiscreteGaussianImageFilter.h # modified: Code/BasicFilters/itkRecursiveGaussianImageFilter.h #
git has compressed the three commits into one, combining the commit messages and the changes to the code. In the original commits, we only modified one file at a time, but in this new commit, three files are modified. Rewriting the commit message to make it look like one big commit gives:
# This is a combination of 3 commits. # The first commit's message is: Added documentation. Added \sa tag in itkRecursiveGaussianImageFilter to reference DiscreteGaussianImageFilter. Added \sa tag in itkDiscreteGaussianImageFilter.h to reference RecursiveGaussianImageFilter. Added \sa tag to reference Recursive and Discrete GaussianImageFilters in itkBilateralImageFilter.h. ...
Now we have a look at our commit history:
So our three commits now look like one. git removed the three commits through the rebase command. Remember that these commits only exist in your local clone of the ITK repository. Next step is to push them into Gerrit.