* This is work in progress *

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

Getting help from the command line

Git documentation is pretty massive - it can definitely be difficult to apprehend. Once you have a good grasp of the basic scenario, you should familiarize yourself with git from the git tutorial, and git for svn users. Only then will you be able to start reading the git included help.

Scenario 1: getting the numpy source code

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

Do NOT use checkout - checkout has a different meaning than in svn. Clone is what you want.

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: prepare a simple patch ala svn, don't bother me with git

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

Maybe: we could have a svn mirror of git ?

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.

Q: I thought that git reset was the option to use ?

No, don't use git reset. Git reset can be used to revert changes, but can be dangerous to use, as it can also remove *commits*, not just changes. git reset is only useful for advanced usage of git. Use git stash or git co, not git reset.

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