Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 31, 2013, 19:41 UTC
Message-ID: <7vip6dgmx2.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20130131190747.GE27340@google.com>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 24 quoted lines

> Junio C Hamano wrote:
>
>> Wow, that's a blast from the past.
>>
>> I tend to agree that deprecating and removing are quite different,
>> but a simple "revert" of the change would not be good, either.  We
>> still would want to _discourage_ its use.
>
> Hm, I was about to try adding a line in that vein, like
>
>  * `tracking` - deprecated synonym for `upstream`.
>  
> Imagine my surprise when I saw that that is what you just said
> would be no good:
>
> [...]
>>>>    `git pull`.
>>>> -* `tracking` - deprecated synonym for `upstream`.
>>>>  * `current` - push the current branch to a branch of the same name.
>
> I really do think that including `tracking` in the same list would be
> valuable.  When I look over a friend's .gitconfig file to help track
> down a problem she is running into, it is helpful if I can find the
> meaning of each item in a straightforward way.

While I agree we would need a way for you to easily find `tracking` mentioned near that point, listing it as if it is a proper part of the same list of possibilities is not the only way to do so.

The enumeration is used by two different audiences. For those who want to _learn_ what possibilities are available to them (i.e. they are not going from `tracking` to what it means, but going in the opposite direction), it should be unmistakingly clear that `tracking` is not a part of the choices they should make. I do not think the following list created by a simple "revert" makes it clear.

    * `nothing` - do not push anything.
    * `matching` - push all branches having the same name in both ends.
    * `upstream` - push the current branch to ...
    * `simple` - like `upstream`, but refuses to ...
    * `tracking` - deprecated synonym for `upstream`.
    * `current` - push the current branch to a branch of the same name.

When scanning, most people will scan lines to see there are 6 choices without reading anything after '-' first, and then start reading the item that sounds plausible for them without necessarily reading the others. That will imprint the word `tracking` in the context of choosing how to push, especially when that is not what they end up using.

That is why I tend to prefer how check-ref-format documentation describes --print:

        --normalize::
                Normalize 'refname' by removing any leading slash (`/`)
                characters and collapsing runs of adjacent slashes between
                name components into a single slash.  Iff the normalized
                refname is valid then print it to standard output and exit
                with a status of 0.  (`--print` is a deprecated way to spell
                `--normalize`.)

When you are going from `tracking` to what it means, you have \C-s (if you are viewing in Emacs) or '/' (if you are using less) available.