Git Primer
From Kokua Wiki
This is a brief overview of how to get the Imprudence source code using Git. We'll try to expand it over time to cover other things you can do with Git.
Note: If you just want the current source, it's easiest just to download a source zip from GitHub.
Make sure that's what you're using when you
clone/push or you'll cause merge conflicts
Contents |
Downloading Git
Recommended:
- Linux: Use your distro's package manager, or compile from source.
- Mac: Git for OS X
- Windows: msysGit
Optional: QGit
QGit is a fairly good graphical interface for Git. It's limited in functionality compared to using the command line, but perhaps friendlier to use. One nice thing is that you can add custom "Actions" to perform commands that it doesn't have built in.
Optional: TortoiseGit
Windows only, gui-based git interface based on TortoiseSVN. 32 bit and 64 bit versions available.
Downloading the Source
The first step to getting the source is to clone the repository. It's called "cloning" because you actually download a copy of the entire repository, including all past and present revisions. That makes the initial download take a little while, but the advantage is that you can then access the entire history of all branches of the source, very quickly, without need for an internet connection. It also allows you to make your own changes without disturbing anyone else's repositories.
The clone URL for the official Imprudence repository is git://github.com/imprudence/imprudence.git
You can clone it from the command line like this:
git clone git://github.com/imprudence/imprudence.git
The results will go into a directory called "imprudence".
Don't forget to download the artwork and libraries as described on the How to compile page!
Switching Branches
The cloned repository contains multiple branches. Each branch contains its own history of changes. Developers can create a new branch and work on it without disturbing any other branches, then merge that branch into another branch to combine them. In Imprudence, we make new branches to fix a bug or implement a new feature, then merge them back into the "next" branch when they are done.
It's important to understand that in Git, you only see the files for one branch at a time. The imprudence directory and its sub-directories show the source code and other files as they exist in the branch you are currently viewing. By default, that's the "master" branch, which contains the files for our most recent release (1.0.0 RC1 as of this writing). To see the newest code (RC2), you need to switch to the "next" branch.
The term Git uses for this is checking out a branch. You can check out the "next" branch from the command line like this:
git checkout next
Or if you like to follow the remote, next branch:
git checkout --track -b next origin/next
(You can use any other branch name in place of the word "next" to switch to that branch instead. To see a list of branches, use git branch)
When you check out another branch, it changes all the project files to match how they exist on that other branch.
Updating Your Repository
Over time, your repository will start to get out of date, because the updates we make to the official repository aren't automatically downloaded to yours. To download the updates, use:
git fetch origin
This means to fetch (download) the updates from the origin (the repository you made the clone of, i.e. the official repository). However, this doesn't automatically apply the updates to your copies of the branches. To do that, use:
git merge origin/next
This merges (combines) the "next" branch that you downloaded from the origin with the branch you are currently visiting. That will bring your branch up to date.
Contributing Code Using Git
First, read Contributing Code to learn how to make the most useful contribution, and decide branch you should work with.
In order to get you contributions back into the official Imprudence repository, go to Github.com, create an account for yourself, then use the fork button on the project page to fork Imprudence's repository.
Then you need to set up SSH so you can push to your Github repository from your local repository. Github gives instructions for MS Windows, Linux, or Mac.
Then back in your local repository, add your new Github fork as a remote
git remote add mygithub git@github.com:MyGithub/imprudence.git
where MyGithub is your Github ID. While you're in your working tree, push your local changes to your Github repository
git push mygithub next
and notify everyone that it's available for integration using the Issue Tracker, as described in Contributing Code.
Git For SVN Users
If you're used to SVN, these guides should help you acclimate to git:
Further Reading
More advanced:
- Git Internals - Recommended by Jacek. Worth the USD $9 price tag if you want to understand why Git works the way it does.
- git-fu
- Git Magic
- Pro Git
