Simpletons guide to git

This is simply a "click these buttons" guide to git. See the last section of the article for more advanced/better guides and resources.

Installing

First, you need to install git. This differs platform to platform..

Linux

On UNIX-like systems, use your package manager to install git-core. You may wish to install git-svn also

For example, on Debian (and Debian based distributions such as Ubuntu):

sudo apt-get install git-core

For Red Hat based distros like Fedora, just change apt-get to yum.

For other distros I'm sure you can figure it out!

Mac OS X, using Mac Ports or fink:

After installing Mac Ports run..

sudo port install git-core

..or for fink run

fink install git-core

Alternatively, you can use the Git for OS X installer.

Windows

Download and install mysysgit

This install a Cygwin terminal with the git commands available, it also installs git gui but I shall assume you are using Cygwin for this tutorial.

From source:

Assuming you have the required development tools (sudo apt-get install build-essential on Ubuntu, or the Developer Tools on OS X), git is simple to compile from source.

Download source code from git-scm.com, extract it. In a terminal cd to the extracted directory and run..

./configure --prefix=/usr/local/git && make && sudo make install

Add /usr/local/git/bin to your $PATH

..alternatively, use the script x-git-update-to-latest-version which uses the latest development version (which I've never had a problem with) - it also deals with installing the man pages, creating symlinks and so on.

Configuration

Now git is setup, there is a few configuration options you should set.

git config --global user.email me@example.com
git config --global user.name 'Alice McBob'

Those are used to identify who made each commit. The email is also used by sites like Github to tie commits to your account.

Final option, to get colours in diffs and the git status output, run the following:

git config --global color.diff auto
git config --global color.status auto

Basics and help

All git commands are of the format:

git [sub command] [arguments]

All sub-commands have their own help, for example:

git add -h

Also, most commands have their own man-page, which can be accessed using --help:

git add --help

This covers the usage of the command in more detail than -h

New repository

Either navigate to your projects folder, or make a new one, cd into it and run:

git init

That is it. This makes the current folder into a git repository (as it now contains a .git/ folder).

Setting up ignores

Make a file named .gitignore - to this file add the files/folders you wish to ignore, one per line. A good base ignore file for Python projects:

*.pyc
.DS_Store
Thumb.db
desktop.ini

That ignores all .pyc files, and a few meta-data files created by OS X and Windows.

Note: The ignore file should be committed to your repository. If you wish to ignore files in your local repository only, use the .git/info/exclude file instead. It's generally best to use .gitignore as this is synced and version-controlled along with your project.

Initial commit

If you run git status you will see all your files are currently "Untracked"

To track all the files (except those excluded by .gitignore), use the git add command on the folder:

git add .

This simply marks the files as "Changes to be committed" - nothing is actually written to the repository, yet.

To commit them into the revision history, run:

git commit

..this will launch your $EDITOR asking for a commit message. You can alternatively specify this on the command line using the -m flag:

git commit -m "Initial commit"

Make changes, see status, commit again

Edit your code. To see what files have changed:

git status

Example output:

# 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:   tvnamer_exceptions.py
#       modified:   utils.py

To see a diff of what has changed, run:

git diff

As mentioned in the git status output, to stage the changes in utils.py simply run:

git add utils.py

Running git status again will now show:

# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   main.py
#
# 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:   tvnamer_exceptions.py

As before, to commit the changes just run:

git commit

That's (sort of) it

That's it. To use git as a local version control system, that's all you need. In summary:

mkdir my_project    # make project folder
cd my_project
git init            # make new repository
# edit your files
git add .           # track all files or changes
git commit          # commit files to revision history
# edit your files more
git add myfile.py   # stage a single file for commiting
git commit          # commit any staged file

Collaboration

To setup a simple "git server" on a remote linux machine, first ssh to it. You then need to create a "bare" repository (basically the contents of the .git folder, without the working copy), to do this run:

mkdir myrepo.git
cd myrepo.git
git init --bare

Naming the folder myrepo.git is just a convention to signify it's a bare repository, it can be named anything.

Now, back on your local machine - you need to tell git where your remote repository is, to do this add a "remote":

git remote add origin myusername@example.com:/some/dir/myrepo.git

To push your changes to this remote you use git push:

git push origin master

master is the default branch name, origin is the server name. Once you have done this once, in future you can simple run

git push

You can have multiple remotes, for example, origin could be your server, you could have a github remote, a mylaptop remote and so on.

If you are pushing to a remote that is not origin you must specify it:

git push github

Now, say someone else has pushed changed to your example.com server, to get these updates you use git pull:

git pull origin master

Once this has been done once, you should be able to simply run git pull.

Note: git fetch is similar to pull, but fetch does not apply changes to your branch. Generally you will want to use git pull (unless you know otherwise)

Github

Setting up your own server is fine, but Github has many advantages, such as a nice repository browser, built-in wiki and issue tracking tools, but the most important thing is the community that surrounds it.

It's extremely simple and self-explanatory to use. Signup for an account (the free one allows you any number of public repositories).

Once logged in, click "create a new repository", enter a project name (and an optional description and homepage URL)

When you click the "Create Repository" button, it presents you with a condensed version of the above guide, showing you how to configure your username/email, make a new (local) repository, add the github remote and push your changes to it!

Additional resources

  • Git Magic Good general guide covering many "How do I.." subjects, such as rewriting revision history, reverting changes and so on. Covers the basics too

  • Gitcasts A series of screencasts covering various topics, including basic setup and workflow, using git log, merging and branching and some more advanced topics like browsing raw git objects (the stuff in the .git folder)

  • The Git Community Book - a community-written book

  • "Pro Git" book - a creative-commons licensed book, written by one of the Github creators

  • "Git for beginners: The definitive practical guide" on StackOverflow Various simple guides created by members of the StackOverflow community. Contains links to other Git resources

  • The git tag on StackOverflow Several "why use git?" discussions, many obscure problems and issues solved, some guides to using git. If you have problems not covered by Git Magic or a quick web-search, StackOverflow is a good place to ask for help!

  • Peepcode Git episode Costs $9USD. Covers basically everything about git

  • "Git For Windows Developers" series (part 1) (also part 2, and part 3)

    Covers using git on Windows. After the initial setup, much of this will apply to any platform.

  • Github Guides Guides created by Github users. Obviously some are Github-oriented, but covers many generalised git topics

  • Utilities:

    • gitosis Best way to host multi-user git repositories on your own server. Simplifies configuration, authentication and so on.
    • GitX - "a git GUI specifically for Mac OS X. It currently features a history viewer much like gitk and a commit GUI like git gui. But then in silky smooth OS X style!"
  • Git hosting:

    • Github - the most popular git hosting site, hosts projects such as Ruby on Rails, some of Digg's open-source porjects and many others. unlimited open-source repositories for free (upto 300MB space), paid accounts have private repositories, good collaboration tools.
    • Gitorious - free, for open-source projects (no private repositories), the site itself is open source
    • repo.or.cz - the more-or-less official git hosting. A bit archiac looking compared to Github/Gitorious
    • Unfuddle - Subversion and Git hosting, free account allows one project. Has various project management tools