ITK/Gerrit/Primer: Difference between revisions

From KitwarePublic
< ITK‎ | Gerrit
Jump to navigationJump to search
(Replaced content with "This page previously contained information on use of Gerrit for ITK. The old information has been removed to avoid confusion. Please get started here instead.")
 
(35 intermediate revisions by 7 users not shown)
Line 1: Line 1:
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 [http://git-scm.com/ git] distributed revision control system.
This page previously contained information on use of Gerrit for ITK.
 
The old information has been removed to avoid confusion.
==Gerrit basics==
Please [[ITK/Git|get started here]] instead.
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===
In order to register you need to [http://openid.net/get-an-openid/ get an OpenID]. Be aware that a [http://www.gmail.com GMail] account automatically gives you an OpenID.
 
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
* Review
* 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 [[ITK/Git|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:
 
[[File:GerritPrimerBranch.png]]
 
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:
 
<pre>
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")
</pre>
 
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:
 
[[File:GerritPrimerCommits.png‎]]
 
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 [http://gitready.com/intermediate/2009/01/31/intro-to-rebase.html 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:
 
<pre>
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.
#
</pre>
 
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:
 
<pre>
pick 1e01adb Added documentation.
squash b465a05 Documentation changes.
squash 7d7f3c1 Documentation changes.
...
</pre>
 
git processes what we've done and puts us back into editing the commit message:
 
<pre>
# 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
#
</pre>
 
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:
 
<pre>
# 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.
...
</pre>
 
Now we have a look at our commit history:
 
[[File:GerritPrimerSquashedCommit.png‎ ]]
 
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.
==== Push your changes into Gerrit ====
First, we need to tell git about the Gerrit server:
 
git remote add gerrit USERNAME@review.source.kitware.com:ITK
 
(be sure to change '''USERNAME''' to your username on the Gerrit server)  This does nothing more than create an alias called '''gerrit''' that can be used for pushing and pulling changes.
 
Gerrit needs to know where we intend the code to go, so we'll push our particular commit to a particular place in Gerrit.  The '''git push''' command takes three arguments, a destination repository, a local commit and a remote location.
 
git push gerrit GerritPrimer:refs/for/master/GerritPrimer
 
'''gerrit''' is the destination repository, '''GerritPrimer''' is our local commit, and '''refs/for/master/GerritPrimer''' is the remote commit name.  We can call the remote commit anything we like, e.g. '''refs/for/master/foo_bar_garf''', but it is sensible to make a useful name.
 
<pre>
revelation:ITK(GerritPrimer) blezek$  git push gerrit GerritPrimer:refs/for/master/GerritPrimer
Counting objects: 11, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 5.88 KiB, done.
Total 7 (delta 4), reused 0 (delta 0)
remote: (W) f62f37: commit message lines >70 characters; manually wrap lines
remote:
remote: New Changes:
remote:  http://review.source.kitware.com/75
remote:
To blezek@review.source.kitware.com:ITK
* [new branch]      GerritPrimer -> refs/for/master/GerritPrimer
revelation:ITK(GerritPrimer) blezek$
</pre>
 
Gerrit has told us that there is a new branch created called GerritPrimer and we can take a look at http://review.source.kitware.com/75.
 
==== Review ====
==== Stage changes into the ITK official repository ====

Latest revision as of 17:30, 3 June 2011

This page previously contained information on use of Gerrit for ITK. The old information has been removed to avoid confusion. Please get started here instead.