Merge pull request #1200 from ben/fetch_push_suggestions

Fetch and push on different repositories

Author: aollier

book/06-github/sections/2-contributing.asc

@@ -43,6 +43,7 @@ Here's how it generally works:
 5. Open a Pull Request on GitHub.
 6. Discuss, and optionally continue committing.
 7. The project owner merges or closes the Pull Request.
+8. Sync the updated master back to your fork.
 
 This is basically the Integration Manager workflow covered in <<ch05-distributed-git#_integration_manager>>, but instead of using email to communicate and review changes, teams use GitHub's web based tools.
 
@@ -417,3 +418,63 @@ This isn't technically GitHub Flavored Markdown, but it is incredibly useful. In
 image::images/markdown-08-drag-drop.png[Drag and drop images]
 
 If you look at <<_md_drag>>, you can see a small ``Parsed as Markdown'' hint above the text area. Clicking on that will give you a full cheat sheet of everything you can do with Markdown on GitHub.
+
+[[_fetch_and_push_on_different_repositories]]
+==== Keep your GitHub public repository up-to-date
+
+Once you've forked a GitHub repository, your repository (your "fork") exists independently from the original.
+In particular, when the original repository has new commits, GitHub informs you by a message like:
+
+[source,text]
+----
+This branch is 5 commits behind progit:master.
+----
+
+But your GitHub repository will never be automatically updated by GitHub; this is something that you must do yourself.
+Fortunately, this is very easy to do.
+
+One possibility to do this requires no configuration.
+For example, if you forked from `https://github.com/progit/progit2.git`, you can keep your `master` branch up-to-date like this:
+
+[source,console]
+----
+$ git checkout master <1>
+$ git pull https://github.com/progit/progit2.git <2>
+$ git push origin master <3>
+----
+
+<1> If you were on another branch, return to `master`.
+<2> Fetch changes from `https://github.com/progit/progit2.git` and merge them into `master`.
+<3> Push your `master` branch to `origin`.
+
+This works, but it is a little tedious having to spell out the fetch URL every time.
+You can automate this work with a bit of configuration:
+
+[source,console]
+----
+$ git remote add progit https://github.com/progit/progit2.git <1>
+$ git branch --set-upstream-to=progit/master master <2>
+$ git config --local remote.pushDefault origin <3>
+----
+
+<1> Add the source repository and give it a name.
+    Here, I have chosen to call it `progit`.
+<2> Set your `master` branch to fetch from the `progit` remote.
+<3> Define the default push repository to `origin`.
+
+Once this is done, the workflow becomes much simpler:
+
+[source,console]
+----
+$ git checkout master <1>
+$ git pull <2>
+$ git push <3>
+----
+
+<1> If you were on another branch, return to `master`.
+<2> Fetch changes from `progit` and merge changes into `master`.
+<3> Push your `master` branch to `origin`.
+
+This approach can be useful, but it's not without downsides.
+Git will happily do this work for you silently, but it won't warn you if you make a commit to `master`, pull from `progit`, then push to `origin` -- all of those operations are valid with this setup.
+So you'll have to take care never to commit directly to `master`, since that branch effectively belongs to the upstream repository.

book/10-git-internals/sections/refspec.asc

@@ -120,6 +120,12 @@ If they want Git to do that automatically each time they run `git push origin`,
 
 Again, this will cause a `git push origin` to push the local `master` branch to the remote `qa/master` branch by default.
 
+[NOTE]
+====
+You cannot use the refspec to fetch from one repository and push to another one.
+For an example to do so, refer to <<ch06-github#_fetch_and_push_on_different_repositories>>.
+====
+
 ==== Deleting References
 
 You can also use the refspec to delete references from the remote server by running something like this: