Guides: Fork a project and submit your modifications

In this guide, we will use github-services as an example to fork, submit a change, and re-sync with the forked repo. All the examples on this page assume you’re working in the “master” branch.

Note that this works for pulling from a forked repository to the original, as well.

Setting up

Naturally, the first thing you must do is create your fork. To do this, you simply click the button on the project’s page. When the fork has completed, you will be presented with your new repo information.

Now you need to clone the fork. Make sure you use the “Your Clone URL” and not the “Public Clone URL”

git clone git@github.com:billyanyteen/github-services.git

Once the clone is complete your repo will have a remote named “origin” that points to your fork on github. Don’t let the name confuse you, this does not point to the original repo you forked from. To help you keep track of that repo we will add another remote named “upstream”

cd github-services
git remote add upstream git://github.com/pjhyett/github-services.git 
git fetch upstream

Note that we used the public clone URL for upstream, so we can’t push changes directly to it. We probably don’t have permission to do that anyway, which is why we’re creating a fork in the first place.

Pushing your changes

Now that we’ve got our fork, we need to make a few changes and commit them locally. Once you’ve done this, it’s time to push your updated branch.

git push origin master

After you’ve pushed your commit(s) you need to inform the project owner of the changes so they can pull them into their repo. From your project’s page, click the button. Fill in a note and pick who to send the request to. In large projects it is important that you do not send the request to every person who’s touched the project. Make sure you’re only sending to the people who care, the user(s) that manage the core project repo.

Note that some projects do not accept pull requests. Make sure you submit your request to the place they want it, or you will probably just be ignored.

Pulling in upstream changes

Some time has passed, the upstream repo has changed and you want to update your fork before you submit a new patch.

git pull upstream master

This command does two things, git fetch upstream master to update your local tracking branch, then git merge upstream/master to bring the changes into your currently checked out branch. If you have local commits that are not in the upstream branch, a normal merge will occur. If your local commits are in the upstream branch, a fast-forward merge will be done, moving your local branch to the same commit as upstream/master. You may have to resolve merge conflicts if there are any.

Now that your local branch has been updated, you can commit, push, and send a pull request.

You may wish to do the fetch and merge manually, instead of letting git-pull do it for you. This can sometimes help avoid headaches caused by mysterious merge conflicts.

Deleting the forked repository

To remove the fork, just delete it like any repo: click the “Edit” button next to “pull request”, then at the bottom of the page there will be a “Delete This Repository…” link.

Additional resources

• github-gem – Handy tool for pulling in forked branches
• Rails on the Run forking tutorial