|Version 2 (modified by cdavid, 4 years ago)|
* This is work in progress *
- Before starting
- Common scenario
- A first few git specific workflows
Please do not use any version of git below 1.5.3.
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, xcode should give you everything which is needed, 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.
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/
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
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 firstname.lastname@example.org
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, as it is meant to be exhaustive and reference-like. This page is intented to help you through the first steps. The suggested way is as follows:
- Read this page.
- Once you have a good grasp of the basic scenario, you could either go to [git for svn users], or to the [git tutorial] for a more "git-oriented" introduction.
- Then the git manpages should be less daunting.
Note: as using svn did not require you to read the svn book, using git does not require reading all those material. It is hoped that this page is more than enough for development in numpy.
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 svn.
Scenario 0: setting up git
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:
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