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.
Debian or Ubuntu: apt-get install git-core 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:
NetBSD: scmgit pkgsrc package
"Git homepage":http://www.git.or.cz/ includes source downloads
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 "email@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
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:
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: