Added a few examples to git-pull man page.

Added a few examples to git-pull man page. Clarified and added notes for pull/push refspecs. Converted to back-ticks for literal text examples.

---

Hmmm. Are back-ticks the standard for literal text examples?

 Documentation/git-pull.txt         |   55 ++++++++++++++++++++++++++--
 Documentation/pull-fetch-param.txt |   72 +++++++++++++++++++++++++-----------
 2 files changed, 101 insertions(+), 26 deletions(-)

applies-to: a469bc3e7efcb96db78bbffcdabcbea01bead34d ca90ebc23d3e6fb73bc7da3e3d893adab8456722

index cef4c0a..8f37d53 100644
@@ -19,7 +19,7 @@ When only one ref is downloaded, runs 'g
 into the local HEAD.  Otherwise uses 'git octopus' to merge them
 into the local HEAD.
 
-Note that you can use '.' (current directory) as the
+Note that you can use `.` (current directory) as the
 <repository> to pull from the local repository -- this is useful
 when merging local branches into the current branch.
 

@@ -29,8 +29,57 @@ include::pull-fetch-param.txt[]
 
 -a, \--append::
 	Append ref names and object names of fetched refs to the
-	existing contents of $GIT_DIR/FETCH_HEAD.  Without this
-	option old data in $GIT_DIR/FETCH_HEAD will be overwritten.
+	existing contents of `$GIT_DIR/FETCH_HEAD`.  Without this
+	option old data in `$GIT_DIR/FETCH_HEAD` will be overwritten.
+
+Examples
+--------
+Command line pull of multiple branches from one repository::
++
+------------------------------------------------
+$ cat .git/remotes/origin
+URL: rsync://rsync.kernel.org/pub/scm/git/git.git
+Pull: master:origin
+
+$ git checkout master
+$ git fetch origin master:origin +pu:pu maint:maint
+$ git pull . origin
+------------------------------------------------
++
+Here, a typical `$GIT_DIR/remotes/origin` file from a
+`git-clone` operation is used in combination with
+command line options to `git-fetch` to first update
+multiple branches of the local repository and then
+to merge the remote `origin` branch into the local
+`master` branch.  The local `pu` branch is updated
+even if it does not result in a fast forward update.
+Here, the pull can obtain its objects from the local
+repository using `.`, as the previous `git-fetch` is
+known to have already obtained and made available
+all the necessary objects.
+
+
+Pull of multiple branches from one repository using `$GIT_DIR/remotes` file::
++
+------------------------------------------------
+$ cat .git/remotes/origin
+URL: rsync://rsync.kernel.org/pub/scm/git/git.git
+Pull: master:origin
+Pull: +pu:pu
+Pull: maint:maint
+
+$ git checkout master
+$ git pull origin
+------------------------------------------------
++
+Here, a typical `$GIT_DIR/remotes/origin` file from a
+`git-clone` operation has been hand-modified to include
+the branch-mapping of additional remote and local
+heads directly.  A single `git-pull` operation while
+in the `master` branch will fetch multiple heads and
+merge the remote `origin` head into the current,
+local `master` branch.
+
 
 Author
 ------

---
0.99.9.GIT

Thanks for the documentation updates. I have one
trouble about this part:

You never do your own development on branches that appear on the right hand side of a <refspec> colon on Pull: lines; they are to be updated by git-fetch. The corollary is that a local branch should be introduced and named on a <refspec> right-hand-side if you intend to do development derived from that branch.
This leads to the common Pull: master:origin mapping of a remote master branch to a local origin branch, which is then merged to a local development branch, again typically named master.

I am a bit confused by the "corollary". What happens if you have the following:

Pull: master:origin
Pull: +pu:pu
Pull: maint:maint

and you say:

git-pull remote

when you are on your master branch is:

1. master, pu and maint from remote are copied to origin, pu, and maint in the local repository (you already know this);

2. the updated origin is merged into the local master (you alerady know this too).

If somebody intends to do development derived from say 'maint', one way to do so would be something like this:

git checkout -b my-maint maint
.. work work work, commit commit commit
.. "git-format-patch maint..my-maint" to send patches .. off, or send a pull request to upstream. git fetch remote ;# to update origin, pu, and maint. git pull . maint ;# merge maint changes into my-maint.

That is, my-maint branch is used for your own development, and from time to time you fetch remote heads (using remotes/remote shorthands, the fetch would update origin, pu and maint) to keep track of the progress of the upstream. And you merge upstream 'maint' into your development line 'my-maint', when you find that the upstream have something new in 'maint'.

And because of the rule "you never do your own development on RHS branch":

git checkout maint
.. work work work, commit commit commit
git pull remote ;# oops

this is discouraged. 'git pull remote' would try to overwrite the local 'maint' with the remote 'maint', and it would find that the head would not fast-forward (obviously, since we did our own work that the remote side does not know about). But when I read the "corollary" the first time, it appeared to me that we are suggesting the above.

Maybe something like this (I know my wording is quite bad and I would appreciate rephrasing it better very much) would be more explicit and appropriate?

If you intend to do development derived from a remote branch B, have a Pull: line to track it, like this:

Pull: B:remote-B

and have a separate branch my-B to do your development on top of it. The latter is created by 'git branch my-B remote-B' (or its equivalent, 'git checkout -b my-B remote-B'), and that is the branch you make your own commits. Run 'git fetch' to keep track of the progress of the remote side, and when you see the tracked remote branch has something new, merge it into your development branch with 'git pull . remote-B', while you are on my-B branch.

It would be good to explicitly mention that exactly this is already setup for you after cloning: you are prepared to do local development based on the remote "master", with
- remote head "B" = remote head "master"
- local head "remote-B" = local head "origin"
- local head "my-B" = local head "master"

Hmm. I just looked up the manual page of "git-clone", but it does not mention this. It also should say that all remote heads are cloned to local heads with the same name, with one exception:
remote "master" matches local "origin".

This feels really inconsistent. Junio, I think your proposal of tracking remote "B" with local "origin/B" is a lot better. It allows to name a local development branch for any remote "B" by the same local name "B".

We could make heads starting with "origin/" special: Never let "git commit" update such a head, but give out a warning instead, that this head should not be changed locally, as it is used for tracking a remote head. This warning could suggest to do "git branch" before committing.
This special handling (of "origin/") should not be hardcoded, but configurable, perhaps in .git/remotes:

URL: remote-URL
Prefix: origin/

Josef