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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 30, 2009, 16:47 UTC
Message-ID: <7vd4bzdkkq.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1238407903-28020-4-git-send-email-santi@agolina.net>

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

Show 18 quoted lines

> 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.