welcome: please sign in
location: GitGuide

The 5-Minute Guide to Contributing with Git

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.

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.

For More Information

Go to the Git homepage. Also check out:

WikiCompleteOrg: GitGuide (last edited August 02, 2012 by JohnGoerzen)