How to Git: a Brief Guide to Making Open-Source Contributions ft. Bridge Troll

Get Started

Totally new to git? GitHub has a great introduction at learn.github.com. We're assuming you have git installed and a basic understanding of using git locally for the purposes of this page.

If you haven't already, configure things:

• $ git config --global user.name "Veronica Mars"
• $ git config --global user.email "veronica@marsinvestigations.com"
• $ git config --global color.ui true

Make your fork: go to the project's GitHub repo and click the Fork button.

Now, clone it to your machine, replacing {username} with your GitHub username:

• $ git clone https://github.com/{username}/bridge_troll.git

Start working in the project directory:

• $ cd bridge_troll

Add the main project repo as an upstream remote so you can pull updates:

• $ git remote add upstream git://github.com/railsbridge/bridge_troll.git

Work on your Code

Make and name a new feature branch:

• $ git checkout -b newfeature

Now write your code!

Stay up to date

You can either wait until you make your pull request to deal with any merge conflicts, or you can update your feature branch as pull requests are merged. If you update while working on your feature, you'll need to commit your work in progress.

To update your feature branch, pull in upstream changes while on that branch:

• $ git fetch upstream
• $ git rebase upstream/master

You can also do these things in a single command that fetches from the URL tracked by the current branch and immediately tries to merge in the tracked branch:

• $ git pull --rebase upstream master

Prep to make a Pull Request

'git rebase' is a command that replays all your commits since a given point, giving you the opportunity to change the commit messages or squash multiple commits into one. When you rebase you add your code changes to the end of the project history, which is cleaner than the alternatives.

Rebase against the newly updated (upstream) code:

• $ git fetch upstream
• $ git rebase -i upstream/master

This will open up an editor that shows you your commits that aren't on the upstream master:

• pick jfd834sf set textbox width better
• pick 92urw73 fix bad choices
• pick dj57skg add html editing

Edit these so that that all but one say squash instead of pick:

• pick jfd834sf set textbox width better
• squash 92urw73 fix bad choices
• squash dj57skg add html editing

Save and quit this, and you'll get a new editor that you can use to create the perfect commit message. Save and quit once you've written it, and you've got one nice commit on top of the most recent updates to the project.

Submit that pull request!

First, push your changes to your fork:

• $ git push origin newfeature

Now, use the GitHub website to make the pull request:

On your fork on GitHub, switch to the branch that you just pushed to. Click the Pull Request button. Review the diff by clicking the "Files Changed" tab and make sure the diff makes sense. Write a compelling explanation of the awesome changes you made, and click Submit Pull Request. First pull request? GitHub has a guide with awesome screen shots.

Make requested changes

Most pull requests don't get merged as-is. The maintainers often have requests for code changes. If you have to make revisions, squash them locally as explained above. You'll then need to force push onto your branch on GitHub, using git push -f origin head while on your feature branch. (Force pushing is something you only do on your own forks of things.)

If you decide to start working on any other features while your pull request is getting reviewed, be sure to make a new branch!