Git for development

These pages describe a general git and github workflow.

This is not a comprehensive git reference. It’s tailored to the github hosting service. You may well find better or quicker ways of getting stuff done with git, but these should get you started.

For general resources for learning git see Additional Git Resources.

Have a look at the github install help pages available from github help

Install git

Developing with git can be done entirely without github. Git is a distributed version control system. In order to use git on your machine you must install it.

Get the local copy of the code

From the command line:

git clone git://github.com/numpy/numpy.git

You now have a copy of the code tree in the new numpy directory. If this doesn’t work you can try the alternative read-only url:

git clone https://github.com/numpy/numpy.git

Updating the code

From time to time you may want to pull down the latest code. Do this with:

cd numpy
git fetch
git merge --ff-only

The tree in numpy will now have the latest changes from the initial repository.

Getting started with Git development

This section and the next describe in detail how to set up git for working with the NumPy source code. If you have git already set up, skip to Development workflow.

Basic Git setup

• Install git.
• Introduce yourself to Git:

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

Making your own copy (fork) of NumPy

You need to do this only once. The instructions here are very similar to the instructions at http://help.github.com/forking/ - please see that page for more detail. We’re repeating some of it here just to give the specifics for the NumPy project, and to suggest some default names.

Set up and configure a github account

If you don’t have a github account, go to the github page, and make one.

You then need to configure your account to allow write access - see the Generating SSH keys help on github help.

Create your own forked copy of NumPy

1. Log into your github account.
2. Go to the NumPy github home at NumPy github.
3. Click on the fork button:

After a short pause, you should find yourself at the home page for your own forked copy of NumPy.

Set up your fork

First you follow the instructions for Making your own copy (fork) of NumPy.

Overview

git clone https://github.com/your-user-name/numpy.git
cd numpy
git remote add upstream https://github.com/numpy/numpy.git

In detail

Clone your fork

1. Clone your fork to the local computer with git clone https://github.com/your-user-name/numpy.git

2. Investigate. Change directory to your new repo: cd numpy. Then git branch -a to show you all branches. You’ll get something like:

   * master
   remotes/origin/master
   

   This tells you that you are currently on the master branch, and that you also have a remote connection to origin/master. What remote repository is remote/origin? Try git remote -v to see the URLs for the remote. They will point to your github fork.

   Now you want to connect to the upstream NumPy github repository, so you can merge in changes from trunk.

Linking your repository to the upstream repo

cd numpy
git remote add upstream https://github.com/numpy/numpy.git

upstream here is just the arbitrary name we’re using to refer to the main NumPy repository at NumPy github.

Just for your own satisfaction, show yourself that you now have a new ‘remote’, with git remote -v show, giving you something like:

upstream     https://github.com/numpy/numpy.git (fetch)
upstream     https://github.com/numpy/numpy.git (push)
origin       https://github.com/your-user-name/numpy.git (fetch)
origin       https://github.com/your-user-name/numpy.git (push)

To keep in sync with changes in NumPy, you want to set up your repository so it pulls from upstream by default. This can be done with:

git config branch.master.remote upstream
git config branch.master.merge refs/heads/master

You may also want to have easy access to all pull requests sent to the NumPy repository:

git config --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pr/*'
Your config file should now look something like (from ``$ cat .git/config``):

[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
        ignorecase = true
        precomposeunicode = false
[remote "origin"]
        url = https://github.com/your-user-name/numpy.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[remote "upstream"]
        url = https://github.com/numpy/numpy.git
        fetch = +refs/heads/*:refs/remotes/upstream/*
        fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*
[branch "master"]
        remote = upstream
        merge = refs/heads/master

Git configuration

Overview

Your personal git configurations are saved in the .gitconfig file in your home directory. Here is an example .gitconfig file:

[user]
        name = Your Name
        email = you@yourdomain.example.com

[alias]
        ci = commit -a
        co = checkout
        st = status -a
        stat = status -a
        br = branch
        wdiff = diff --color-words

[core]
        editor = vim

[merge]
        summary = true

You can edit this file directly or you can use the git config --global command:

git config --global user.name "Your Name"
git config --global user.email you@yourdomain.example.com
git config --global alias.ci "commit -a"
git config --global alias.co checkout
git config --global alias.st "status -a"
git config --global alias.stat "status -a"
git config --global alias.br branch
git config --global alias.wdiff "diff --color-words"
git config --global core.editor vim
git config --global merge.summary true

To set up on another computer, you can copy your ~/.gitconfig file, or run the commands above.

In detail

user.name and user.email

It is good practice to tell git who you are, for labeling any changes you make to the code. The simplest way to do this is from the command line:

git config --global user.name "Your Name"
git config --global user.email you@yourdomain.example.com

This will write the settings into your git configuration file, which should now contain a user section with your name and email:

[user]
      name = Your Name
      email = you@yourdomain.example.com

Of course you’ll need to replace Your Name and you@yourdomain.example.com with your actual name and email address.

Aliases

You might well benefit from some aliases to common commands.

For example, you might well want to be able to shorten git checkout to git co. Or you may want to alias git diff --color-words (which gives a nicely formatted output of the diff) to git wdiff

The following git config --global commands:

git config --global alias.ci "commit -a"
git config --global alias.co checkout
git config --global alias.st "status -a"
git config --global alias.stat "status -a"
git config --global alias.br branch
git config --global alias.wdiff "diff --color-words"

will create an alias section in your .gitconfig file with contents like this:

[alias]
        ci = commit -a
        co = checkout
        st = status -a
        stat = status -a
        br = branch
        wdiff = diff --color-words

Editor

You may also want to make sure that your editor of choice is used

git config --global core.editor vim

Merging

To enforce summaries when doing merges (~/.gitconfig file again):

[merge]
   log = true

Or from the command line:

git config --global merge.log true

Two and three dots in difference specs

Thanks to Yarik Halchenko for this explanation.

Imagine a series of commits A, B, C, D… Imagine that there are two branches, topic and master. You branched topic off master when master was at commit ‘E’. The graph of the commits looks like this:

     A---B---C topic
     /
D---E---F---G master

Then:

git diff master..topic

will output the difference from G to C (i.e. with effects of F and G), while:

git diff master...topic

would output just differences in the topic branch (i.e. only A, B, and C).

Additional Git Resources

Tutorials and summaries

• github help has an excellent series of how-to guides.
• learn.github has an excellent series of tutorials
• The pro git book is a good in-depth book on git.
• A git cheat sheet is a page giving summaries of common commands.
• The git user manual
• The git tutorial
• The git community book
• git ready - a nice series of tutorials
• git casts - video snippets giving git how-tos.
• git magic - extended introduction with intermediate detail
• The git parable is an easy read explaining the concepts behind git.
• Our own git foundation expands on the git parable.
• Fernando Perez’ git page - Fernando’s git page - many links and tips
• A good but technical page on git concepts
• git svn crash course: git for those of us used to subversion

Advanced git workflow

There are many ways of working with git; here are some posts on the rules of thumb that other projects have come up with:

• Linus Torvalds on git management
• Linus Torvalds on linux git workflow . Summary; use the git tools to make the history of your edits as clean as possible; merge from upstream edits as little as possible in branches where you are doing active development.

Manual pages online

You can get these on your own machine with (e.g) git help push or (same thing) git push --help, but, for convenience, here are the online manual pages for some common commands:

• git add
• git branch
• git checkout
• git clone
• git commit
• git config
• git diff
• git log
• git pull
• git push
• git remote
• git status