Re: [PATCH] Added a few examples to git-pull man page.

[Junio C Hamano <junkio@cox.net>]

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.