= git mirror =

[[PageOutline]]

As of March 2010, an experiment in mirroring the svn source repository to git has been started. Information on how to use and contribute are listed below.

== Requisits ==

git, obviously :
 * on Windows :
  * command line with [http://msysgit.googlecode.com/files/Git-1.6.5.1-preview20091022.exe msysgit]
  * explorer integration with [http://code.google.com/p/tortoisegit/downloads/list TortoiseGit]
 * on Mac :
   * command line [http://code.google.com/p/git-osx-installer/downloads/list git installer]
   * gitk : comes in with git and is a graphical local repository browser
   * [http://gitx.frim.nl/GitX ] 
 * on Linux
  * git : command line : `sudo apt-get install git-core`
  * gitk :  graphical local repository browser : `sudo apt-get install gitk`
  * git-gui : A Tcl/Tk based graphical user interface to Git `sudo apt-get install git-gui`

 === What is git anyway ? ===

'''[http://progit.org Pro Git Book]''' or '''[http://book.git-scm.com/index.html Git Community Book]''' is a good start ! But you might be more interested in the [http://git.or.cz/course/svn.html Git - SVN Crash Course] : git explained to svn users.

Also have a look at  [http://whygitisbetterthanx.com/ Why git is better than X]

== Location ==

The mirror is hosted on [http://github.com github] AND [http://gitorious.org gitorious] see comments at the end of this page on pros ans cons of these services

 on github : http://github.com/openscenegraph/osg [[BR]]
 on gitorious : http://gitorious.org/openscenegraph/osg

== Workflow ==
=== Read-Only ===
This workflow is intended for users who need to stay on top of OpenSceneGraph activity but do not intend to modify it for they own need nor contribute some enhancements or bug correction back.

==== Initial checkout ====

{{{
#!sh
~ $ git checkout git://github.com/openscenegraph/osg.git
}}}

In case you are behind a restrictive firewall try opening TCP/IP port 9418 or use the http (slow) version as shown :

{{{
#!sh 
~ $ git checkout http://github.com/openscenegraph/osg.git
}}}

==== Update ====
{{{
#!sh
~/OpenSceneGraph $ git pull
}}}

=== Contributor ===

Contributor workflow

When planning to contribute to OpenSceneGraph you need to record your changes so they can be pulled into the upstream by the maintainer.

This is largely inspired from Michael Norton's [http://docondev.blogspot.com blog entry Doc On Dev] : [http://docondev.blogspot.com/2010/02/contributing-to-project-you-find-on.html ''Contributing to a project you find on GitHub'']

You will need a [https://github.com GitHub] account

==== 1. Fork the OpenSceneGraph project ====
                                    
Login to github. Go to [http://github.com/openscenegraph/osg http://github.com/openscenegraph/osg]'s git mirror project

To create a fork, press the "fork" button on the project's page.
[[Image(osg-contributor-fork.png)]]

When the fork is complete, you will have a copy of the project in your repositories listing.
[[Image(osg-contributor-repositories.png)]]

==== 2. Clone your project ==== 

Now back on your computer you need to clone your fork. Make sure you use the “Your Clone URL” and not the “Public Clone URL”. You want to be able to push changes back to your own repository.

{{{
#!sh
~ $ git clone git@github.com:[your-github-account]/osg.git
}}}

Once the clone is complete your repo will have a remote named “origin” that points to your fork on github. You will use "origin" for your own regular activities.
  
{{{
#!sh
~/osg (master)$ git remote -v
origin	git@github.com:[your-github-account]/osg.git (fetch)
origin	git@github.com:[your-github-account]/osg.git (push)
}}}

==== 3. Link your repository to the upstream ====   

 ''upstream''::
   ''repository that you forked''  

To keep track of the modifications committed to the 'upstream' branch of the project you need to add a remote branch to your local repository

{{{
#!sh
~/osg (master)$ git remote add upstream git://github.com/openscenegraph/osg.git
}}}

You should now have another remote :

{{{
#!sh
~/osg (master)$ git remote -v
origin	git@github.com:[your-github-account]/osg.git (fetch)
origin	git@github.com:[your-github-account]/osg.git (push)
upstream	git://github.com/openscenegraph/osg.git (fetch)
upstream	git://github.com/openscenegraph/osg.git (push)
}}}
     
====  4. Create a branch containing your contribution ==== 

First step is to create a branch to make your modifications. Lets call it topic :

{{{
#!sh
~/osg (master)$ (master)> git checkout -b topic
Switched to a new branch 'topic'
~/osg (topic)$ git branch
  master
* topic
}}}

Now make your modifications to the project and commit them to your topic branch. 

==== 5. Keep your fork up-to-date ==== 

Forking a repository is the recommended way of contributing to a github project. Alas it doesn't get updated with the latest commits from the forked repository.

The upstream remote we added in the previous topic will help you update your repository with those latest changes by pulling and then merging in them in as so :  

{{{
#!sh
~/osg (master)$ git pull upstream master
}}}

Now your local upstream/master should contain all the new commits. You can merge them to your master branch.

{{{
#!sh
~/osg (master)$ git merge upstream/master
}}}


==== 6. Keep your contributions up-to-date ====           

When updating your repository with the upstreams modifications it is likely that your topic branch will need to integrate those changes too. This is called ''[http://book.git-scm.com/4_rebasing.html rebasing]''. This will modify your topic branch commits (yes, it will create some new commits) to make the topic branch start from the latest commits in the upstream repository. The illustrations are taken from the '''[http://book.git-scm.com/index.html Git Community Book]''', `origin` -> `master` and `mywork` -> `topic` in our case.

before : [[Image(http://book.git-scm.com/assets/images/figure/rebase1.png)]]
{{{
#!sh
~/osg (topic)$ git rebase master
}}}
after : [[Image(http://book.git-scm.com/assets/images/figure/rebase4.png)]]

==== 7. Submitting your contribution  ==== 

Work in Progress...

== Mirorring process ==

The mirorring process was fairly simple :
 1. use [http://github.com/mathieu/svn2git svn2git] (my mirror added a --continue flag if the execution failed the svn fetch process) :
{{{
#!sh
~ $ svn2git http://www.openscenegraph.org/svn/osg/OpenSceneGraph
}}} 
 2. add remotes to push changes to 
{{{
#!sh
~/OpenSceneGraph (master)$ git remote add github git@github.com:openscenegraph/osg.git
~/OpenSceneGraph (master)$ git remote add gitorious git@gitorious.org:openscenegraph/osg.git
}}}
 3. create a shell script `osg-svn2git.sh` to update and push changes
{{{
#!sh
#!/bin/sh
cd ~/OpenSceneGraph
/usr/bin/git svn fetch
/usr/bin/git merge trunk
/usr/bin/git push --mirror gitorious
/usr/bin/git push --mirror github
}}}
 4. add the shell script to the crontab
{{{
*/5 * * * * ~/osg-svn2git.sh
}}}

== Services Pros & Cons ==
|| || github || gitorious ||
|| downloads|| + [http://github.com/openscenegraph/osg/downloads source archive per tag] || - manual upload of archives ||