From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 31 Jan 2013 19:41:45 GMT
Subject: Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Message-ID: <7vip6dgmx2.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20130131190747.GE27340@google.com>

Jonathan Nieder <jrnieder@gmail.com> writes:

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