History

The 5-Minute Guide to Contributing With Git

The 5-Minute Guide to Contributing With GitStep 1: Get GitStep 2: Configure GitStep 3: Check Out The SourceStep 4: HackStep 5: SubmitStep 6: UpdateAdvanced Tips & TricksLearning About CommandsLooking At ChangesPretty ColorsFor More Information

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://git.complete.org/projectname
cd projectname

Replace "projectname" with the Git name for your project. These names will be given on the project page on this site. One example would be:

git clone git://git.complete.org/listlike
cd listlike

The Software.Complete.Org project list and Git.Complete.Org project list may be of use to you.

If the checkout fails or hangs: you may be behind a restrictive firewall. In those cases, substitute http:// instead of git://. It'll be slower, but it'll work. In the above example, that would be: git clone http://git.complete.org/listlike

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 will usually be jgoerzen AT complete DOT org

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

You can, of course, use the project timeline here on the website. But for more detailed information, 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:

Also available in: HTML TXT