Difference between revisions of "Slicer:git-svn"

From Slicer Wiki
Jump to: navigation, search
(22 intermediate revisions by 9 users not shown)
Line 11: Line 11:
 
For these instructions we'll assume you are using [http://github.com github] so make yourself an account there (it's free and pretty simple).  Configure the account with your email, name, and ssh keys.  The git tutorials are never-ending, so don't try to read them all at once.  The only way to get good with git is to play around with some dummy repositories while reading various documents until you feel reasonably confident with the way things work.
 
For these instructions we'll assume you are using [http://github.com github] so make yourself an account there (it's free and pretty simple).  Configure the account with your email, name, and ssh keys.  The git tutorials are never-ending, so don't try to read them all at once.  The only way to get good with git is to play around with some dummy repositories while reading various documents until you feel reasonably confident with the way things work.
  
== Make a local clone of Slicer ==
+
Update your git settings so that it remove directories from the SVN tree if there are no files left behind, configure it globaly:
 +
git config --global svn.rmdir true
  
git svn clone -s -r 16923 http://svn.slicer.org/Slicer4
+
See http://man.github.com/git/git-svn.html
  
The -s says that slicer uses the standard trunk/tags/branches svn layout and the -r says grab the code at revision 16923 (just to keep things smaller).
+
== Make a local clone of Slicer ==
The command above tries to checkout the "trunk" branch of the svn repository, so revision 16923 must exist within the "trunk" branch.  Note: use the URL http://svn.slicer.org/Slicer3 to access the Slicer3 svn repository.
 
  
Then update to get the most recent:
+
Then, check out a read-only version of Slicer your own copy and associate it with slicer's svn:
  
cd Slicer4
+
  git clone git://github.com/Slicer/Slicer.git
git svn fetch
+
  cd Slicer
git checkout master
+
  git svn init http://svn.slicer.org/Slicer4/trunk
 +
  git update-ref refs/remotes/git-svn refs/remotes/origin/master
 +
  git svn rebase
  
Jim needed an extra step here to have the checkout sit at HEAD and not at R16923
+
Note that <code>git://github.com/Slicer/Slicer.git</code> is read-only, no one can push on it. A robot synchronizes the svn repository with the github repository (svn ->git, not git -> svn).
 
 
git svn rebase
 
  
== push it to github ==
+
== Optional - push it to your own github repository ==
  
On github, create a new repository for your account called Slicer4.
+
First, fork the Slicer/Slicer.git project on github into your own account (this will save space on github):
 +
* Go to [https://github.com/Slicer/Slicer https://github.com/Slicer/Slicer]
 +
* and click on the ''Fork'' button.  
  
 
Then set up a 'git remote' (basically an alias) to your git hub repository:
 
Then set up a 'git remote' (basically an alias) to your git hub repository:
 
+
cd Slicer
  git remote add pieperSlicer4 git@github.com:pieper/Slicer4.git
+
  git remote add pieperSlicer4 git@github.com:pieper/Slicer.git
  
 
(of course, replace occurrences of 'pieper' with your github username!).
 
(of course, replace occurrences of 'pieper' with your github username!).
Line 69: Line 71:
 
Now if you look at the github repository it will have your new branch and commits.  And you can easily email the link to the diffs off to your collaborators.  They can review them, or check them out, make their own clones, or (with your permission) edit and commit back to your branch.
 
Now if you look at the github repository it will have your new branch and commits.  And you can easily email the link to the diffs off to your collaborators.  They can review them, or check them out, make their own clones, or (with your permission) edit and commit back to your branch.
  
== Merging back to the master ==
+
To work on the same branch on a different machine (for example, if you want to work out cross-platform build issues) you can checkout the repository and the create a tracking branch for your topic.  Something like this:
 +
 
 +
git branch --track testbranch pieperSlicer4/testbranch
 +
 
 +
then you can push into that branch from the new machine as well.
 +
 
 +
== Committing back to svn ==
 +
 
 +
Once you have the code from the branch just the way you want it, you can put it directly back into svn (do not merge it back into master).
  
 +
While in the branch with the changes you want to commit, bring it in sync with svn by doing, essentially, the same as 'svn update':
  
Once you have the code from the branch just the way you want it, you can merge it back to the master:
+
git svn rebase
  
  git checkout master
+
then you can commit
git merge testbranch
+
 +
  git svn dcommit --add-author-from
 +
 
 +
Note: you may need to use git commit --amend to edit the commit message to add "ENH:", "COMP:", "BUG:" etc. to be compatible with slicer svn.
  
 
Since we're done with this branch, we can clean it up:
 
Since we're done with this branch, we can clean it up:
  
  git branch -d testbranch
+
  git branch -D testbranch
 +
 
 +
(use the capital D to delete the branch even though it is not merged to master)
  
 
And, we can get rid of it off of github:
 
And, we can get rid of it off of github:
Line 87: Line 103:
 
  git push pieperSlicer4 :testbranch
 
  git push pieperSlicer4 :testbranch
  
== Committing back to svn ==
+
== How it looks in svn ==
 +
 
 +
These are normal svn operations, so once they are commited (with dcommit) they show up as normal (example here is from Slicer3):
 +
 
 +
File created: http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15512
 +
File modified: http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15514
 +
File deleted (using svn, just for cleanliness): http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15513
 +
 
 +
 
 +
 
 +
 
 +
== Alternate Import from svn with History ==
 +
 
 +
This will pull the git-svn hash history from the existing repo, (avoids calculating from the beginning), then update to the current svn revision.
 +
 
 +
 
 +
git svn clone -s -r 16923 http://svn.slicer.org/Slicer4
 +
 
 +
The -s says that slicer uses the standard trunk/tags/branches svn layout and the -r says grab the code at revision 16923 (just to keep things smaller).
 +
The command above tries to checkout the "trunk" branch of the svn repository, so revision 16923 must exist within the "trunk" branch.  Note: use the URL http://svn.slicer.org/Slicer3 to access the Slicer3 svn repository.
 +
 
 +
 
 +
Then update to get the most recent:
 +
 
 +
cd Slicer4
 +
git svn fetch
 +
git checkout master
  
Bring your local master in sync with svn by doing, essentially, the same as 'svn update':
+
Jim needed an extra step here to have the checkout sit at HEAD and not at R16923
  
 
  git svn rebase
 
  git svn rebase
  
then you can commit
 
 
git svn dcommit
 
  
Note: you may need to use git commit --ammend to edit the commit message to add "ENH:", "COMP:", "BUG:" etc. to be compatible with slicer svn.
+
== Pull request from a git-svn tracking branch ==
 +
 
 +
If you have been running git-svn for any length of time, the commit hash history will have diverged from the Official Github history at http://github.com/Slicer/slicer. This will result in very dirty pull requests from your fork (no, you really don't want to merge 803 commits!)
 +
 
 +
To generate a "clean" pull request, do the following:
 +
 
 +
1) Add upstream
 +
  git remote add upstream https://github.com/Slicer/Slicer.git
 +
2) Update, if any changes:
 +
  git fetch upstream/master (NOTE: don't use pull, it will generate nasty merge commits by default)
 +
3) rebase the feature branch:
 +
  git rebase upstream/master myFeature
 +
 
 +
This will change the commit hash history to match that of upstream/master.
 +
 
 +
4) Now push the feature to github:
 +
  git push origin myFeature
 +
It should now be possible to issue a clean pull request against Slicer/slicer with *only* the commits in myFeature listed by github.
 +
 
 +
 
 +
== Integrating topic from external contributor ==
 +
 
 +
The idea is to use the option <code>--add-author-from</code> associated with <code>git svn dcommit</code> so that a <code>From:</code> field is added to the commit message.
  
== How it looks in svn ==
+
<pre>
 +
From: Jean-Christophe Fillion-Robin <myname@kitware.com>
 +
</pre>
  
These are normal svn operations, so once they are commited (with dcommit) they show up as normal (example here is from Slicer3):
+
=== Single patch approach ===
  
File created: http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15512
+
  git checkout master
File modified: http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15514
+
  git svn rebase
File deleted (using svn, just for cleanliness): http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15513
+
  git checkout -b 2885-add-ruler-projection-on-2D-viewers
 +
  curl -O https://github.com/lchauvin/Slicer/commit/203b44301c0421d619d68e2ccd3a13dee0047cf0.patch
 +
  git apply 203b44301c0421d619d68e2ccd3a13dee0047cf0.patch
 +
  gitk  # <- always check what's going on :-)
 +
  git svn dcommit --add-author-from
  
== Alternate import with history ==
+
=== Cherry-pick approach ===
Importing the full svn history is slow... One way around this is to specify a late revision number as above (and even this can take a while).
 
  
Another option is to get the history from an existing git-svn'd repo:
+
  git checkout master
 +
  git svn rebase
 +
  git checkout -b 2885-add-ruler-projection-on-2D-viewers
 +
  git remote add laurent git://github.com/lchauvin/Slicer
 +
  git fetch laurent
 +
  git cherry-pick <the sha1 of the commit>
 +
  gitk  # <- always check what's going on :-)
 +
  git svn dcommit --add-author-from
  
# git clone git@github.com:Slicer/Slicer.git
+
=== Complete topic approach ===
# git svn init http://svn.slicer.org/Slicer4/trunk
 
# git update-ref refs/remotes/git-svn refs/remotes/origin/master
 
# git svn rebase
 
  
This will pull the git-svn hash history from the existing repo, (avoids calculating from the beginning), then update to the current svn revision.
+
  git checkout master
 +
  git svn rebase
 +
  git remote add laurent git://github.com/lchauvin/Slicer
 +
  git fetch laurent
 +
  git checkout -b 2885-add-ruler-projection-on-2D-viewers laurent/2885-add-ruler-projection-on-2D-viewers
 +
  git svn rebase
 +
  gitk  <- always check what's going on :-)
 +
  git svn dcommit --add-author-from
  
 
== More git resources ==
 
== More git resources ==
Line 125: Line 202:
 
Here are a bunch of links that may help:
 
Here are a bunch of links that may help:
  
 +
* [http://marklodato.github.com/visual-git-guide/index-en.html A Visual Git Reference]
 
* https://cirl.berkeley.edu/mb312/gitwash/index.html
 
* https://cirl.berkeley.edu/mb312/gitwash/index.html
 
* http://www.itk.org/Wiki/ITKContribute
 
* http://www.itk.org/Wiki/ITKContribute
Line 136: Line 214:
 
* http://github.com/pkgwdemo/bloomdemo
 
* http://github.com/pkgwdemo/bloomdemo
 
* http://marklodato.github.com/visual-git-guide/#merge
 
* http://marklodato.github.com/visual-git-guide/#merge
 +
* [http://pcottle.github.com/learnGitBranching/ Git branching visual tutorial]

Revision as of 20:38, 1 February 2017

Home < Slicer:git-svn

Intro

As of 2011 the 3D Slicer projects use subversion (svn) for the main repositories. Many project are switching to git and many developers prefer it, but feedback is also mixed about just how easy it is for a large distributed team to standardize on a set of workflows and stick with them (much anecdotal evidence and hearsay omitted).

But, individual developers or groups can use git for their work and then commit the results back to svn. The info here provides a brief set of hints for this.

Prerequisites

Install git and git-svn on your machine (git svn is an add-on package, requiring an extra apt-get install on ubuntu).

For these instructions we'll assume you are using github so make yourself an account there (it's free and pretty simple). Configure the account with your email, name, and ssh keys. The git tutorials are never-ending, so don't try to read them all at once. The only way to get good with git is to play around with some dummy repositories while reading various documents until you feel reasonably confident with the way things work.

Update your git settings so that it remove directories from the SVN tree if there are no files left behind, configure it globaly:

git config --global svn.rmdir true

See http://man.github.com/git/git-svn.html

Make a local clone of Slicer

Then, check out a read-only version of Slicer your own copy and associate it with slicer's svn:

 git clone git://github.com/Slicer/Slicer.git
 cd Slicer
 git svn init http://svn.slicer.org/Slicer4/trunk
 git update-ref refs/remotes/git-svn refs/remotes/origin/master
 git svn rebase

Note that git://github.com/Slicer/Slicer.git is read-only, no one can push on it. A robot synchronizes the svn repository with the github repository (svn ->git, not git -> svn).

Optional - push it to your own github repository

First, fork the Slicer/Slicer.git project on github into your own account (this will save space on github):

Then set up a 'git remote' (basically an alias) to your git hub repository:

cd Slicer
git remote add pieperSlicer4 git@github.com:pieper/Slicer.git

(of course, replace occurrences of 'pieper' with your github username!).

The following command will populate the github master with your Slicer4 master (which is based on trunk).

git push pieperSlicer4 master

Create a topic branch

The 'branchy workflow' method of git is cool because all the changes related to a topic (meaning bug fix, feature addition, refactoring...) can be encapsulated in a lightweight branch that you can easily share with others.

Create a branch called "testbranch" for implementing our topic:

git checkout -b testbranch

(use 'git branch' to list branches and see that you are currently on the testbranch).

Now do some edits. If you create a new file, add it for tracking like so:

echo "new stuff" > newfile
git add newfile

As you make the changes, commit them to your local copy and give descriptive comments:

git commit -am "ENH: added a new file with new stuff  ..."

(in reality we prefer that you don't use the -m flag and instead us your editor to write a fairly long commit message with as much detail as you can stand to type). Also be sure to start your commit message with ENH, BUG, COMP, STYLE... for compatibility with the slicer svn rules.

Whenever you want to sync this up to github, just do:

git push pieperSlicer4 testbranch

Now if you look at the github repository it will have your new branch and commits. And you can easily email the link to the diffs off to your collaborators. They can review them, or check them out, make their own clones, or (with your permission) edit and commit back to your branch.

To work on the same branch on a different machine (for example, if you want to work out cross-platform build issues) you can checkout the repository and the create a tracking branch for your topic. Something like this:

git branch --track testbranch pieperSlicer4/testbranch

then you can push into that branch from the new machine as well.

Committing back to svn

Once you have the code from the branch just the way you want it, you can put it directly back into svn (do not merge it back into master).

While in the branch with the changes you want to commit, bring it in sync with svn by doing, essentially, the same as 'svn update':

git svn rebase

then you can commit

git svn dcommit --add-author-from

Note: you may need to use git commit --amend to edit the commit message to add "ENH:", "COMP:", "BUG:" etc. to be compatible with slicer svn.

Since we're done with this branch, we can clean it up:

git branch -D testbranch

(use the capital D to delete the branch even though it is not merged to master)

And, we can get rid of it off of github:

git push pieperSlicer4 testbranch --delete
or 
git push pieperSlicer4 :testbranch

How it looks in svn

These are normal svn operations, so once they are commited (with dcommit) they show up as normal (example here is from Slicer3):

File created: http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15512 File modified: http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15514 File deleted (using svn, just for cleanliness): http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=15513



Alternate Import from svn with History

This will pull the git-svn hash history from the existing repo, (avoids calculating from the beginning), then update to the current svn revision.


git svn clone -s -r 16923 http://svn.slicer.org/Slicer4

The -s says that slicer uses the standard trunk/tags/branches svn layout and the -r says grab the code at revision 16923 (just to keep things smaller). The command above tries to checkout the "trunk" branch of the svn repository, so revision 16923 must exist within the "trunk" branch. Note: use the URL http://svn.slicer.org/Slicer3 to access the Slicer3 svn repository.


Then update to get the most recent:

cd Slicer4
git svn fetch
git checkout master

Jim needed an extra step here to have the checkout sit at HEAD and not at R16923

git svn rebase


Pull request from a git-svn tracking branch

If you have been running git-svn for any length of time, the commit hash history will have diverged from the Official Github history at http://github.com/Slicer/slicer. This will result in very dirty pull requests from your fork (no, you really don't want to merge 803 commits!)

To generate a "clean" pull request, do the following:

1) Add upstream

 git remote add upstream https://github.com/Slicer/Slicer.git

2) Update, if any changes:

 git fetch upstream/master (NOTE: don't use pull, it will generate nasty merge commits by default)

3) rebase the feature branch:

 git rebase upstream/master myFeature

This will change the commit hash history to match that of upstream/master.

4) Now push the feature to github:

 git push origin myFeature

It should now be possible to issue a clean pull request against Slicer/slicer with *only* the commits in myFeature listed by github.


Integrating topic from external contributor

The idea is to use the option --add-author-from associated with git svn dcommit so that a From: field is added to the commit message.

From: Jean-Christophe Fillion-Robin <myname@kitware.com>

Single patch approach

 git checkout master
 git svn rebase
 git checkout -b 2885-add-ruler-projection-on-2D-viewers
 curl -O https://github.com/lchauvin/Slicer/commit/203b44301c0421d619d68e2ccd3a13dee0047cf0.patch
 git apply 203b44301c0421d619d68e2ccd3a13dee0047cf0.patch
 gitk  # <- always check what's going on :-)
 git svn dcommit --add-author-from

Cherry-pick approach

 git checkout master
 git svn rebase
 git checkout -b 2885-add-ruler-projection-on-2D-viewers
 git remote add laurent git://github.com/lchauvin/Slicer
 git fetch laurent
 git cherry-pick <the sha1 of the commit>
 gitk  # <- always check what's going on :-)
 git svn dcommit --add-author-from

Complete topic approach

 git checkout master
 git svn rebase
 git remote add laurent git://github.com/lchauvin/Slicer
 git fetch laurent
 git checkout -b 2885-add-ruler-projection-on-2D-viewers laurent/2885-add-ruler-projection-on-2D-viewers
 git svn rebase
 gitk  <- always check what's going on :-)
 git svn dcommit --add-author-from

More git resources

(There is more info on git than anyone can really digest - unfortunately I often find that the information you need is not exactly described by the man page or tutorial you are currently reading. The only solution is to read widely, don't believe everything you read, skip the parts that seem too wordy or abstract, and experiment a lot.)

Here are a bunch of links that may help: