This is for those who haven't used git before and need a crash-course on basic
operations. I'll keep this as simple as possible, and focus specifically on
working on Stone Soup, rather than git in general. I've also added links to
the official git docs at the end, which you can read instead of, or in addition
to this, if you're inclined.
Installing git
--------------
I strongly recommend using at least git 1.6 or later. While you can use older
versions, the newer versions are much more user-friendly. This guide assumes
you're using 1.6.
Linux: Install git using your package manager. The git package is usually
called git-core.
Mac: Install git using Mac ports or Fink. The MacPorts port is called git-core
(sudo port install git-core).
Windows: Install MSYS2 (git-for-windows.github.io/#contribute). See the detailed
instructions in INSTALL.txt for further setup information. Be sure to download
the 'Git for Windows SDK', as this also includes all of the necessary tools
to build Crawl - other installers include only Git itself.
Using git for Stone Soup development
------------------------------------
0. Basic git settings:
Set your name for git to use when committing changes:
$ git config --global user.name "John Doe"
Set your email address:
$ git config --global user.email "jdoe@users.sourceforge.net"
This sets your default e-mail id for all git work on your system. You can
use any e-mail address you have. In the above, John Doe is still using his
old sourceforge id as a spam-catching measure.
1. Clone the crawl repository from github (analogous to svn checkout):
Developers (anyone with commit rights to the git repo):
$ git clone git@github.com:crawl/crawl.git
Other users:
$ git clone https://github.com/crawl/crawl.git
"git clone" clones Crawl's entire git repository to your machine. When it's
done, you have a full local copy of the crawl repository with all its
history.
If you want to build the contributing libraries rather than using the
versions already installed on your system, you can fetch the submodules:
$ cd crawl
$ git submodule update --init
2. Sanity-check your cloned repository (optional):
When you come back to a git repository after a while, you may not recall
where you cloned it from. You can check with:
$ git remote -v
This reports:
origin git@github.com:crawl/crawl.git (fetch)
origin git@github.com:crawl/crawl.git (push)
See all available branches in the repository:
$ git branch -a
See all tags:
$ git tag
3. SSH keys (for core developers):
If you want to push to the Github repository, you will need to create an ssh
key and upload your public key to github.com.
Let's create an ssh key (if you already have a key, skip this step):
$ ssh-keygen
You can accept all the default options and use an empty passphrase for
convenience (don't do this on an account you share with other people, or
they can commit to the repository too :P)
Once the key is generated, you'll have two files id_rsa, and id_rsa.pub in
your ~/.ssh (the .ssh directory in your home directory). id_rsa is your
private key, and should not be shared or given to anyone else (or they can
pretend to be you); id_rsa.pub is your public key, and this is what you'll
upload to github.
Go to github.com, login, and from the menu bar, hit the setting gear icon at
the top-right to access your account settings. Click on "SSH keys" and then
on "Add SSH key".
Enter your account name or another descriptive name as the title. Copy the
one line in your id_rsa.pub, and paste it into the Key text area. Hit Save
when you're done.
Within a few minutes of uploading your key, you should be able to push/pull
from github.com.
Windows users (msysgit) can follow these exact same steps in a git bash
prompt.
4. Updating your repository with the latest changes from github.com:
Use
$ git pull
to grab the latest commits from github.com.
git pull assumes your working tree is clean; it will refuse to overwrite any
files that you've modified locally (unlike svn's "svn update", which will
happily try to modify the file anyway, and add conflict markers if there are
conflicts).
If git pull fails because you have local changes, you have two options:
1. Complete your local changes and create a commit, then pull
again.
2. Temporarily save (stash) your local changes, pull changes from github,
and reapply your local changes:
$ git stash
(this saves your local changes)
$ git pull
(grab changes from github)
$ git stash apply
(reinstate your local changes)
If your local changes conflict with the changes from github, git stash
apply will warn you of the conflict and add conflict markers to the
relevant files.
5. Committing a change to the 'master' branch:
git's master branch is the equivalent of svn trunk. Immediately after
cloning a repository, the cloned crawl repo will be on the master
branch. You can check what branch you're working on at any time with:
$ git branch
The active branch will be asterisked.
Before starting work, let's make sure our working copy is not dirty:
$ git status
# On branch master
nothing to commit (working directory clean)
Looking good. For our first change, let's assume we're fixing a bug in, say,
player.cc.
$ vim player.cc
<hackhackhack>
$ make
<test; that bugfix rocks the world>
Let's check how git sees things now:
$ git status
# On branch master
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: player.cc
#
no changes added to commit (use "git add" and/or "git commit -a")
git sees that we've modified player.cc. You can see what changes you've made
with:
$ git diff
Time to actually commit the change:
$ git commit -a
git will bring up your preferred editor for you to enter your commit
message. On Windows, you may have to set your EDITOR environment variable;
alternatively, you can specify your commit message on the command line:
$ git commit -a -m "Fitted player.cc with mountain dwarves"
When you're done, your change has been committed to your local
repository. Let's try git status again:
$ git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit (working directory clean)
So git's telling us that we have one local commit that we haven't sent to
github's git repository yet. Let's send in our fix to github.com (core devs
only):
$ git push
You will be prompted for your password again. git should then push your
commit, producing a last line that looks like:
54ea5f1..ec2e15e master -> master
The exact commit ids will differ, but a successful push looks like
this. Your push may fail if someone has pushed changes to github already
(git will warn you about a non-fast-forward). In this case, just pull and
push again:
$ git pull
$ git push
6. Patching (for regular contributors, not core devs):
Once you have commited and tested a change, you can create a patch for it.
You can then send this patch to the devs or upload it to a mantis issue for
review and potential addition to the game.
To start, make and save your changes in whatever text editor you choose.
Then, as explained above, commit those changes:
$ git commit -a
In most cases, this is a good time to compile and test the change. Make sure
it works correctly, testing in Wizard Mode as appropriate.
When you're happy with your patch, you can make a patch file with the
format-patch command. For example:
$ git format-patch -1
This will create a patch from the most recent commit you've made. The patch
file will be placed in your base Crawl source directory.
For a more detailed patch creation guide, check out patch_guide.txt in the
/docs/develop/ directory.
7. Viewing revision history:
You can see a history of changes with
$ git log
git log by itself may make it appear that the change history is a straight
line, but we know that git can handle branching histories. We can request
that git log show us the branching history with:
$ git log --graph
You can also view history using the gitk GUI (this is installed by default;
everyone should have it, and I recommend it):
$ gitk
The history commands normally show you the history of the current branch,
but you can view other branches/tags' histories by naming the branch or tag:
$ gitk origin/stone_soup-0.16
If you want to annotate a file with last author and commit to change each
line in the file, you can use git blame, which is similar to svn blame:
$ git blame player.cc
8. Committing a change to a different branch:
So far we've restricted our attention to 'master', which is the easiest
branch to work with, since it's selected by default. Now let's say we have a
bug report with a 0.16 save, and we need the 0.16 code to test the save
with:
Let's take a look at the branches we have locally:
$ git branch
* master
The only local branch in our repository is master. Let's look at
the branches in the remote repository (github):
$ git branch -r
origin/HEAD -> origin/master
origin/master
origin/stone_soup
...
origin/stone_soup-0.16
So our local repository has a "master" branch corresponding to github's
"master" branch. We do not yet have a branch corresponding to github's
"stone_soup-0.16", so let's create the branch and switch to it. By default
git will find find the branch origin/stone_soup-0.16 and create a local
branch that tracks this one:
$ git checkout stone_soup-0.16
Branch stone_soup-0.16 set up to track remote branch stone_soup-0.16
from origin.
Switched to a new branch 'stone_soup-0.16'
master and stone_soup-0.16 are both local branches now:
$ git branch
master
* stone_soup-0.16
git status will also confirm that we're on 0.16 now:
$ git status
# On branch stone_soup-0.16
nothing to commit (working directory clean)
A quick peek at the history to make really sure we're on 0.16:
$ git log
To grab the latest changes for 0.16:
$ git pull
Ok, now we compile 0.16, test the 0.16 save and verify that a bug
exists. Once we've fixed the bug, we create a commit:
$ git commit -a
Check git status:
$ git status
# On branch stone_soup-0.16
# Your branch is ahead of 'origin/stone_soup-0.16' by 1 commit.
#
nothing to commit (working directory clean)
Right, we're ready to push our fix to github.
$ git push --dry-run -v
Pushing to git@github.com:crawl/crawl.git
To git@github.com:crawl/crawl.git
b05bb66..976e722 stone_soup-0.16 -> stone_soup-0.16
So git wants to push the local stone_soup-0.16 branches to the corresponding
branches on github. Run the same command without --dry-run to actually push
the commit.
Once you're done working on 0.16, you can switch back to "master"
with:
$ git checkout master
The next time you need to work on 0.16 again, you can return to it
with:
$ git checkout stone_soup-0.16
9. Common operations:
Reverting Changes
-----------------
It often happens that you make a change to a file that you didn't
want, or accidentally delete files that you did want. You can
revert a file to its pristine version as:
$ git checkout player.cc
This also works to bring back files you accidentally deleted. If
you forget these commands, "git status" will remind you:
$ git status
# On branch master
# Changed but not updated:
# (use "git add/rm <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# deleted: mt19937ar.cc
#
no changes added to commit (use "git add" and/or "git commit -a")
Adding New Files
----------------
When committing changes with "git commit -a", newly created files
won't be added to the commit unless you request it with "git add".
Let's take an example:
$ git status
# On branch master
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# dwim.cc
nothing added to commit but untracked files present (use "git add" to track)
Before we commit, we must add the new file:
$ git add dwim.cc
$ git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# new file: dwim.cc
$ git commit -a
In general, "git status" is your friend. It will usually tell you
exactly what you need to do.
10. Branching:
Let's say we want to create a branch with some tentative or incomplete
changes that we want others to look at or change. Here's how you'd do it,
using a branch called pizza_tornado as an example:
a) Branch pizza_tornado from master:
$ git checkout -b pizza_tornado master
Let's check our local branches now:
master
stone_soup-0.16
* pizza_tornado
pizza_tornado is currently a *local* branch. github's git repo doesn't
have it yet.
b) Push the local branch to github with a --dry-run first to make sure we're
not lousing up anything:
$ git push --dry-run -v origin pizza_tornado
Pushing to git@github.com:crawl/crawl.git
To git@github.com:crawl/crawl.git
* [new branch] pizza_tornado -> pizza_tornado
Now for the real push:
$ git push origin pizza_tornado
c) Point your local branch at the new branch in github:
Now that we've created the branch on github, we want to set up our local
"pizza_tornado" to get changes from github's "pizza_tornado" when we do a
git pull. We do this as:
Tell git that pizza_tornado's remote repository is on github:
$ git config branch.pizza_tornado.remote origin
And that the corresponding branch in github is pizza_tornado:
$ git config branch.pizza_tornado.merge refs/heads/pizza_tornado
Now you can pull changes from github's pizza_tornado branch:
$ git pull
This is only necessary for new branches that you create locally and push
to github. This configuration is automatically set up for you when you
work with branches that already exist on github.
11. Committing changes from one major branch of development to another:
Once we create a stable branch (say 0.16), we usually make all changes to
trunk, but apply bugfixes to the 0.16 branch as well. You can apply changes
from master to stone_soup-0.16 with git cherry-pick:
$ git checkout master
[ make the changes for the bugfix ]
$ git commit -a
$ git checkout stone_soup-0.16
And cherry-pick the tip commit of the master branch (the bugfix we just
committed there):
$ git cherry-pick -x master
If the commit you want to cherry-pick is not the tip of a branch, just use
the commit's id:
$ git cherry-pick -x b0ed1449
git push will then send in the commits from both branches.
Additional Reading:
------------------
I've intentionally kept my examples very simple and glossed over a lot of
details. I've covered the common operations in the svn workflow, but git can do
much more for you if you spend a little time learning it.
git documentation central:
http://git-scm.com/documentation
git tutorial:
http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
Another crash course for svn users:
http://git-scm.org/course/svn.html
