Re: [PATCHv2 3/4] Documentation: branch.*.merge can also afect 'git-push'

[Junio C Hamano <gitster@pobox.com>]

Santi Béjar <santi@agolina.net> writes:

> Signed-off-by: Santi Béjar <santi@agolina.net>
> ---
>  Documentation/config.txt |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 7ae584f..38ab785 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -480,7 +480,7 @@ branch.<name>.remote::
>  branch.<name>.merge::
>  	It defines, together with branch.<name>.remote, the upstream branch
>  	for the given branch. It tells 'git-fetch'/'git-pull' which
> -	branch to merge.
> +	branch to merge and can also afect 'git-push' (see push.default).
>  	When in branch <name>, it tells 'git-fetch' the default
>  	refspec to be marked for merging in FETCH_HEAD. The value is
>  	handled like the remote part of a refspec, and must match a

I'll take [1/4] and [2/4] with minor rewording, and I think [4/4] is not
necessary (push.default is clear enough---and defaultMode won't make it
any clearer to the first time readers anyway as it is unspecified what
kind of "mode" it is talking about).

I do not understand this [3/4].  I did look at push.default but it is
unclear how this variable is involved.

Perhaps it is because the word "tracking" in the description "push the
current branch to the branch it is tracking" is used without explaination.
I think the author meant to say if your local branch frotz by default
merges changes made to the branch nitfol of the remote repository, "frotz
tracks nitfol", but the use of the word "track" for that meaning appears
nowhere in Documentation/glossary-content.txt

When you have:

        [branch "frotz"]
                remote = xyzzy
                merge = nitfol
        [remote "xyzzy"]
                url = ...
                fetch = refs/heads/*:refs/remotes/xyzzy/*

we can learn from the glossary the following:

 * refs/remotes/xyzzy/nitfol is a (remote) tracking branch and is used to
   follow changes made on "nitfol" branch in another repository "xyzzy".

 * refs/heads/*:refs/remotes/xyzzy/* is a refspec.  It shows refs under
   refs/heads/ (aka "local branches") of the "xyzzy" repository are copied
   to our refs/remotes/xyzzy/ hierarchy.

There is no word defined to describe what "nitfol" is to "frotz".  It is
what "frotz" merges from.  So perhaps the description of push.default
should say that, instead of using the word "track" in a confusing way to
describe unrelated concept.  Saying "merge" might confuse people who want
to use "branch.<name>.rebase", so it might be a good idea to say:

	frotz updates with nitfol

To "track" is pretty much about one-way communication.  You track the
other guy, but you do not have to (and often you cannot) update the
upstream with what you do.  branch.<name>.merge may have been "tracking"
in that sense, but with the push.default set to tracking, suddenly the
communication becomes bidirectional and it is not about tracking anymore.