From c23fb9bed7a6a6f87fbdb1d5450d9f658e2da043 Mon Sep 17 00:00:00 2001 From: Ryan Tomayko Date: Sun, 29 Aug 2010 22:32:44 -0700 Subject: [PATCH] fewer words on forking page + link to pull-requests page --- _posts/2009-06-11-forking.markdown | 67 +++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 19 deletions(-) diff --git a/_posts/2009-06-11-forking.markdown b/_posts/2009-06-11-forking.markdown index db011a8..dc99a4a 100755 --- a/_posts/2009-06-11-forking.markdown +++ b/_posts/2009-06-11-forking.markdown @@ -6,64 +6,93 @@ categories: collaborating popular main_category: collaborating --- -This guide will step you through the process of forking, pushing your changes, and pulling in changes from the upstream repo. +This guide will step you through the process of forking, pushing your changes, +and pulling in changes from the upstream repo. -In this guide, we will use [github-services](http://github.com/pjhyett/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. +We'll use [github-services](http://github.com/pjhyett/github-services) as an +example to fork, submit a change, and re-sync with the forked repo. -Note that this works for pulling from a forked repository to the original, as well. +All of 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 "fork" button on the project's page. When the fork has completed, you will be presented with your new repo information. +First, create your fork. Click the *Fork* button on the project's page. You +will be presented with the information for your newly forked repository: ![Fork you](http://img.skitch.com/20100125-8tykuy41tn39emcbsrxy545e9f.jpg) -Now you need to clone the fork. Make sure you use the Private URL and __not__ the Public one. +Now clone the fork locally. Make sure you use the *Private URL*, __not__ the +*Public 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" +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
+$ 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. If the upstream repo is private, you must use its private URL. +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. If the upstream repo is private, +you must use its private URL. 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
+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: -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 "pull request" 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. +
$ git push origin master
-_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._ +Once you've pushed your commit(s), inform the project owner of the changes so +they can pull them into their repo. The best way to do this is by [sending a +pull request](/pull-requests/). 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. There are two ways to do this: +Some time has passed, the upstream repo has changed and you want to update your +fork before you submit a new patch. There are two ways to do this: + 
$ git fetch upstream
 $ git merge upstream/master
$ git pull upstream master
-`git pull` is a more direct way, but the merge it performs can be confusing if the user doesn't expect it and a merge conflict results. `git fetch` will also grab all branches, where `git pull` will only grab the one specified. +`git pull` is a more direct way, but the merge it performs can be confusing if +the user doesn't expect it and a merge conflict results. `git fetch` will also +grab all branches, where `git pull` grabs only the one specified. -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. If both repos have edits to the same location in the same file, you may run into a merge conflict. Conflicts must be resolved by hand and a commit made to complete the merge. +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. If both repos have edits to the same location in the same +file, you may run into a merge conflict. Conflicts must be resolved by hand and +a commit made to complete the merge. -Now that your local branch has been updated, you can commit, push, and send a pull request. +Now that your local branch has been updated, commit your changes, push, and +[send a pull request](/pull-requests/). -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. +You may wish to do the fetch and merge manually, instead of letting git-pull do +it for you. This can help avoid headaches caused by mysterious merge conflicts. Deleting the forked repository ------------------------------ -To remove the fork, just delete it like any repo: click the "Admin" button next to "Unwatch", then at the bottom of the page there will be a "Delete This Repository…" link. +To remove the fork, delete it like any repo: click the *Admin* button, then the +*Delete This Repository…* button. Additional resources -------------------- * [hub](http://github.com/defunkt/hub) * [github-gem](http://github.com/defunkt/github-gem) -* [Rails on the Run forking tutorial](http://railsontherun.com/2008/3/3/how-to-use-github-and-submit-a-patch) \ No newline at end of file +* [Rails on the Run forking tutorial](http://railsontherun.com/2008/3/3/how-to-use-github-and-submit-a-patch)