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

[Jonathan Nieder <jrnieder@gmail.com>]

Junio C Hamano wrote:

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

That works because, as you mention, the usual way to look up an option
in manpages is to search for "--print", including the two minus signs.

Unfortunately an analagous approach in gitconfig(5) would be seriously
broken, because searching for "tracking" (no minus signs) is going to
hit many false positives.  I do not think such a change would be an
improvement.

Meanwhile I believe the prominent words "deprecated synonym" already
make it completely obvious that when I write a new config file, I should
use the modern option, unless I am trying to write a config file that
also works with older versions of git.  In the latter case (which
unfortunately is not too uncommon), hiding the option is not going to
make my life easier.  What would allow me to make an informed choice
is mentioning what version of git *introduced* the new name of the
option:

	- `tracking` - deprecated old name for `upstream`, used by git
	  versions before 1.7.4.2.  Don't use this.

Also I do not think anyone claimed we are removing "tracking" from the
documentation in order to stop people from using it.  The rationale
when the patch was proposed is that it makes the documentation easier
to read.  I agree with that rationale, with the caveat Avar mentioned.
There is a simple fix: just simplify the behavior being explained as
well, by biting the bullet and dropping the "tracking" synonym after a
suitable period in which it produces a warning.

In the meantime, the documentation is valuable, and pretending that
"tracking" does not exist for everyone who does not confusedly reread
the docs a few times is just a way to lie to ourselves and make users'
lives more difficult.  Is that really the intent?

Jonathan