1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
---
layout: default
title: Forking a project
description: How to fork a project, submit changes, and pull from other repos in the fork network
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.
We'll use [github-services](http://github.com/github/github-services) as an
example to fork, submit a change, and re-sync with the forked repo.
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
----------
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:
Now clone the fork locally. Make sure you use the *Private URL*, __not__ the
*Public URL*.
<pre class="terminal">$ git clone git@github.com:billyanyteen/github-services.git</pre>
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":
<pre class="terminal">$ cd github-services
$ git remote add upstream git://github.com/github/github-services.git
$ git fetch upstream
</pre>
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:
<pre class="terminal">$ git push origin master</pre>
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:
<pre class="terminal">$ git fetch upstream
$ git merge upstream/master</pre>
<pre class="terminal">$ git pull upstream master</pre>
`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.
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 help avoid headaches caused by mysterious merge conflicts.
Deleting the forked repository
------------------------------
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)
|
