Git for development
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 firstname.lastname@example.org 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
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
- Log into your github account.
- Go to the NumPy github home at NumPy github.
- 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.
git clone https://github.com/your-user-name/numpy.git cd numpy git remote add upstream https://github.com/numpy/numpy.git
Clone your fork
Clone your fork to the local computer with git clone https://github.com/your-user-name/numpy.git
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
masterbranch, and that you also have a
origin/master. What remote repository is
git remote -vto 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
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
Your personal git configurations are saved in the
.gitconfig file in your home directory. Here is an example
[user] name = Your Name email = email@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 firstname.lastname@example.org 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.
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 email@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 = firstname.lastname@example.org
Of course you’ll need to replace
Your Name and
email@example.com with your actual name and email address.
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 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
You may also want to make sure that your editor of choice is used
git config --global core.editor vim
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
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
git push --help, but, for convenience, here are the
online manual pages for some common commands: