push: Re-include "push.default=tracking" in the documentation

Change the documentation for push.tracking=* to re-include a mention of what "tracking" does.

The "tracking" option was renamed to "upstream" back in 53c4031 ("push.default: Rename 'tracking' to 'upstream'", 2011-02-16), this section was then subsequently rewritten in 87a70e4 ("config doc:
rewrite push.default section", 2013-06-19) to remove any mention of "tracking".

Maybe we should just warn or die nowadays if this option is in the config, but I had some old config of mine use this option, I'd forgotten that it was a synonym, and nothing in git's documentation mentioned that.

That's bad, either we shouldn't support it at all, or we should document what it does. This patch does the latter.

---
 Documentation/config.txt | 4 ++++
 1 file changed, 4 insertions(+)

index 32f065c..f30d52a 100644
@@ -2344,6 +2344,10 @@ push.default::
   pushing to the same repository you would normally pull from
   (i.e. central workflow).
 
+* `tracking` - Deprecated synonym for `upstream`, which we still
+  support for backwards compatibility with existing configuration
+  files.
+
 * `simple` - in centralized workflow, work like `upstream` with an
   added safety to refuse to push if the upstream branch's name is
   different from the local one.

2.9.3

I vaguely remember a similar discussion and probably even a patch in the past (maybe by you actually). I think the proposal was to add a mention of tracking but avoid promoting it at the same level as the others.

I have a slight preference for a patch adding stg like "tracking is a deprecated alias supported only for backward compatibility" to the item of upstream, but I'm OK with the current patch too.

Matthieu Moy
http://www-verimag.imag.fr/~moy/

You're right! I wasn't trying to be sneaky here, but apparently I just keep running into the same things. We talked about this back in 2012, kicked off by you proposing a patch to remove it completely from config.txt and me submitting this:
http://www.spinics.net/lists/git/msg198264.html

After some back & forth Junio ended up applying fa23348 to address that, but that was wiped away just a few months later in 87a70e4.

I'd just like it mentioned in the docs in some way, because I *did* run into exactly the situation I described in my E-Mail back in 2012, i.e. found a repo with push.default=tracking and couldn't find any mention of what it did in the docs.

Junio, looks like from the 2013 discussion that you preferred just having that mention in parenthesis instead of its own item, how about just re-applying your fa23348 (with conflicts resolved)?

(fa23348 did this:

@@ -1749,7 +1749,8 @@ push.default::
   +
   This is currently the default, but Git 2.0 will change the default
   to `simple`.
-* `upstream` - push the current branch to its upstream branch.
+* `upstream` - push the current branch to its upstream branch
+  (`tracking` is a deprecated synonym for this).

)

I agree that doing the same thing is the best option.

Matthieu Moy
http://www-verimag.imag.fr/~moy/

Sorry, I wasn't paying attention to this thread.

It seems that 87a70e4ce8 ("config doc: rewrite push.default section", 2013-06-19) removed that mention by accident? The log message of the commit does not say it actively wanted to remove mention of tracking and/or why it wanted to do so, so I agree that resurrecting that parenthetical mention is the easiest course of action at this point.

However.

With today's description of push.default choices, each of which is a full fledged paragraph, I no longer have the objection I had in

https://public-inbox.org/git/[email protected]/

against having tracking as a separate bullet item. If we add

* tracking - a deprecated synonym for upstream; do not use this.

to today's list, it would stand out as something different from others and it will not cause the confusion I feared in the discussion we had in early 2013. As Jonathan Nieder argued in the thread back then, having it as one of the bullet point would help people locate it without using "search" \C-s or / feature.

Change the documentation for push.tracking=* to re-include a mention of what "tracking" does.

The "tracking" option was renamed to "upstream" back in 53c4031 ("push.default: Rename 'tracking' to 'upstream'", 2011-02-16), this section was then subsequently rewritten in 87a70e4 ("config doc:
rewrite push.default section", 2013-06-19) to remove any mention of "tracking".

Maybe we should just warn or die nowadays if this option is in the config, but I had some old config of mine use this option, I'd forgotten that it was a synonym, and nothing in git's documentation mentioned that.

That's bad, either we shouldn't support it at all, or we should document what it does. This patch does the latter.

---

And neither was I it would appear, and for a much longer time...

Makes senes. Here's a re-send that fixes this. I slighly changed the wording you suggested to be consistent with the other existing cases in config.txt:

5 matches for "eprecated.*for" in buffer: config.txt
2328: This is a deprecated synonym for repack.writeBitmaps.
2462:* tracking - This is a deprecated synonym for upstream.
2813: Deprecated alias for 'sendemail.smtpEncryption = ssl'.
2853: Deprecated alias for sendemail.signedoffbycc.
3180: Deprecated alias for versionsort.suffix. Ignored if

 Documentation/config.txt | 2 ++
 1 file changed, 2 insertions(+)

index eccc012672..988659e16c 100644
@@ -2459,6 +2459,8 @@ push.default::
   pushing to the same repository you would normally pull from
   (i.e. central workflow).
 
+* `tracking` - This is a deprecated synonym for `upstream`.
+
 * `simple` - in centralized workflow, work like `upstream` with an
   added safety to refuse to push if the upstream branch's name is
   different from the local one.

2.11.0