* This is work in progress *

Common scenario

Those scenario are the basics - they are written to minimize as much as possible disruption from the common svn workflows. They are not necessarily the best ways to do a specific task under git, but they are the least surprising for someone used to git.

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.

Scenario 4: simple commits, no branching

To do a commit, use the commit option:

git commit -am "My commit."

The -m option has the same meaning as the svn commit command. By default (without the "-a"), git only commits the changes you explicitly told him about with the add command (TODO: ref to git-specific workflows). Although extremely useful, it can be a bit confusing at first when you come from a svn background, hence the -a option.

A big difference of git compared to svn which cannot be skipped even at this level: git clone gives you a working tree (a snapshot of the sources at one revision) AND the repository with the full history. It means in particular that committing a change will NOT propagate it to the original repository you cloned from. For this, you need to use push:

git push git.scipy.org/git/numpy

TODO: handling of remote locations.

A first few git specific workflows

Before showing a few simple but powerful git-specific workflows, we need to talk about two features of git. One, branches, is not specific to git, but the index concept is, and a basic understanding is necessary for most git-specific workflows.

The branch concept

Git, like other DVCS, is strongly designed around the notion of branches. Instead of everyone committing directly to the trunk, most development happen in branches, which are then merged into the trunk. What's the point, you may ask ?

• commit is fast: it is instantaneous.
• branches are isolated: if you work on a non trivial feature, having a separate branch means you can commit regularly on it, without pushing things into the "trunk". In particular, you can break things without disturbing anyone else.
• branches are a useful unit of decomposition. Although it still certainly makes sense to commit things directly into the main line of development, regularly using separate branches is a good way to split tasks. This is especially useful for reviews: having a separate branch means everyone can easily look at those changes only. The examples will obviously make this clearer.

The index and content-oriented tracking

In the simple scenarios, we mentioned the '-a' option as necessary to commit all changes. That's because in git, you have to explicitly say which changes you want in a commit. Although a minor inconvenience in simple cases, this is extremely useful in advanced cases, especially for complex merges (to deal with conflict). This is linked to the fundamental idea that git tracks content, and not files. When you do

git add foo.c

You are not really adding the file foo.c to the repository, but you add its content to the git repository.

Scenario 1: creating a new branch

Creating a new branch to make my changes.

# Create a branch from an old branch named oldbranch
git branch newbranch oldbranch
# Switch to the new branch
git checkout newbranch

This can be done in one command:

git co -b newbranch oldbranch

Now, every commit will be put in newbranch. Again, as for commits, the branch is only created in your repository, and not propagated to the remote repository, unless you explicitly push for it:

# This push all the changes in newbranch onto the remote repository
git push url_repo newbranch

Scenario 2: comparing branches

This is one example where git is much more powerful AND easier than svn :) To compare HEAD of two branches (that is the last revision of each branch), you simply use the branch1..branch2 syntax:

# Get the diff "between" two branches
git diff oldbranch newbranch
# Get the log of commits "between" two branches
git log oldbranch newbranch

We use "between" very loosely. For the simple following scenario:

• o -- o -- o oldbranch

\ -- o -- o newbranch

Where o is one commit, the above commands will give you the commits specific to newbranch AND the commits from oldbranch since newbranch was started. To get only the changes related to the commit *specific* to new branch, use the ... syntax instead:

git diff oldbranch...newbranch
git log oldbranch...newbranch

Note the difference between '..' and '...'. '..' (2 dots) is the same as a space.

Scenario 3: Merging branches

Merging branches is easy:

# Will merge branch1 into the current branch
git merge branch1

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