5-Minute Git Guide

Welcome. This will be fast. This guide describes how you can contribute to software projects here using the Git version-control system.

Git is a distributed VCS, so you do not need to be granted commit access in advance. You can hack, commit, and then send in your patches without permission from anyone.

Step 1: Get Git

These instructions assume you have git 1.5.1 or above.

Debian or Ubuntu: `apt-get install git-core git-email`

* Debian binary package pages: git-core[1], git-email[2]

1: http://packages.debian.org/

2: http://packages.debian.org/git-email

* Ubuntu binary package pages: git-core[3], git-email[4]

3: http://packages.ubuntu.com/git-core

4: http://packages.ubuntu.com/git-email

Fedora: git-core package is in Fedora Extras, though in Fedora 7 that merged with Fedora Core.

* `yum install git-core`

FreeBSD: git port

Mac OS X:

Installer package

DarwinPorts/MacPorts Package

Fink package

* Or you can try building it yourself using one of these guides:

Guide 1

Guide 2

NetBSD: scmgit pkgsrc package

Windows: msysgit download page[5] and other Windows information[6] (you want the MingW/msys version)

5: http://code.google.com/p/msysgit/downloads/list

6: http://git.or.cz/gitwiki/WindowsInstall

"Git homepage":http://www.git.or.cz/[7] includes source downloads

7: http://www.git.or.cz/

Step 2: Configure Git

Now we'll run a few commands to teach Git about you:

  git-config --global user.name "My Name"
  git-config --global user.email "myemail@example.com"

If you aren't on Unix, or if you're not going to use sendmail to send out mail, configure email with your SMTP server information:

  git-config --global sendemail.smtpserver smtp.example.com

If your server requires you to log in, you'll also want to give:

  git-config --global sendemail.smtpuser "myusername"
  git-config --global sendemail.smtppass "myPassWord"

Step 3: Check Out The Source

You'll run:

  git clone git://example.com/projectname
  cd projectname

The real URL will be given from your project.

If the checkout fails or hangs

In the event of trouble, you may be behind a restrictive firewall. In those cases, substitute `http://` instead of `git://`. It'll be slower, but it'll work in some cases. In the above example, that would be:

  git clone http://example.com/projectname
  cd projectname

Step 4: Hack

Make your changes. After modifying a file, run:

  git commit -a

An editor will be opened for you to describe what you changed. By convention, the first line will be a 1-line summary, and the rest of the lines will describe your change in more detail.

If you add a new file, you'll need to tell Git about it before you can use `commit`:

  git add filename

To rename a file, don't just use a command such as `mv`. Instead, use:

  git mv oldfilename newfilename

And finally, if you delete a file, use `git rm filename` to tell Git about it.

Then `git commit -a` like usual.

Step 5: Submit

Once you're done with your feature, submit it to the software manager(s) for consideration. Make sure you have run `git commit -a`. Then, simply run:

  git format-patch -M -C --stdout origin > submit
  git send-email submit

All version-control history, including your name, commit messages, individual changes, etc. will be e-mailed. You will be prompted for the address to email to.

This, of course, requires a working email setup on your system. You can alternatively attach the submit file to an email using your standard mail client, which will also work.

Step 6: Update

If you follow a project for more than a few hours, you'll want to periodically integrate changes from the upstream repository into your local copy.

  git fetch
  git rebase origin

will do this.

Advanced Tips & Tricks

You may also be interested in some of these.

Learning About Commands

`git help` will show you some of the commands. `git command --help` will show you information about each command.

Looking At Changes

Try a command such as:

  git log

Pretty Colors

If you want pretty colors in your terminal, run:

  git-config --global color.branch auto
  git-config --global color.diff auto
  git-config --global color.interactive auto
  git-config --global color.status auto
  git-config --global color.pager false

I wouldn't try this on Mac or Windows, where your terminals may not be capable of showing the colors properly.