* This is work in progress *

Rationale for git

Comparison with bzr / hg, problems of svn.

How to do the migration

The migration from svn repository to git repository should keep as mush information from svn as possible: history, tags and branches.

Tool for the migration

svn-all-fast-export: see http://repo.or.cz/w/svn-all-fast-export.git

This is an exporter coded by KDE people to handle KDE migration - thus, it can certainly handle numpy and scipy. It can skip some branches, or paths outside the usual trunk/branches/tags (f2py-research, for example), and export svn "tags" as real tags.

usage

For numpy, the following seems to work - it ignores branches outside the /branches namespace, convert the tags.

#!
create repository myproject
end repository

match /trunk/
  repository myproject
  branch master
end match

# Ignore extra 'repositories' which are not numpy code, but were in numpy
# repository.
match /f2py-research/
end match
match /vendor/
end match
match /numpy.sunperf/
end match
match /cleaned_math_config/
end match
match /numpy-docs/
end match

# Take usual svn branches
match /branches/([^/]+)/
  repository myproject
  branch \1
end match

# This rule will create tags that don't exist in any of the
# branches. It's not what you want.
# See the merged-branches-tags.rules file
match /tags/([^/]+)/
  repository myproject
  branch refs/tags/\1
end match

Common scenario

Scenario 0: setting up git

Installation

Please do not use any version of git below 1.5.3.

Linux

Git is included in most linux distributions (git-core on Ubuntu).

Mac OS X

Reasonably up to date binary installers can be found here: http://code.google.com/p/git-osx-installer/.

Installing git itself from sources is easy, but installing the documentation (man, html and info) is a PITA, with many dependencies (asciidoc, etc...). So avoid it if you don't want to go through the hassle.

Windows

There are two easy ways to install git: the native installer or the cygwin installer. Unless you are a regular user of cygwin, the native installer is the best choice. It can be found there: http://code.google.com/p/msysgit/

GUI

Git has a basic TK-based GUI, called gitk. It works well to navigate the history. There are native UI for git for most platforms, including windows and mac os X:

• TortoiseGit?: http://code.google.com/p/tortoisegit/
• gitx (native mac os X client): http://gitx.frim.nl

basic configuration

At minimum, set up your name and email, so that they appear correctly for commits:

git config --global user.name "Your Name Comes Here"
git config --global user.email name@domain.example.com

You can add some aliases so that some git commands spell like the svn ones. The following are useful:

git config alias.co checkout
git config alias.ci commit
git config alias.st status

Scenario 1

Getting the sources from the NumPy? repository, just to look at the sources, or to build from last version instead of released:

git clone http://git.scipy.org/git/numpy numpy

A tarball will also be made available on the scipy website, so that you don't need git at all in this scenario.

Scenario 2

I have found a bug, and I want to submit a patch. I want to do it like in svn, I don't care about git:

# This will list the changed files
git status
# This will put the changes into a patch
git diff

Scenario 3: reverting changes

I have made some changes, but I am confused, I just want to restart from last revision and throw everything away.

There are several solutions - do NOT use revert, git revert is totally different from svn revert. The safe and easy one:

git stash

This will put your changes aside (in a 'stash'), and your working tree will be exactly as if you checked out from the last revision of your repository. It is safe because your changes are not lost - you can reapply them:

git stash apply

If you really don't care about the changes, and are ready to throw them away with no change of recovering: use the checkout option:

git co myfile

This will have the same semantics as svn revert.