Git Primer

From Kokua Wiki
Jump to: navigation, search

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.

Imprudence uses LF (Unix) line endings
Make sure that's what you're using when you
clone/push or you'll cause merge conflicts

Contents

Downloading Git

Recommended:

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: