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

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

[Ævar Arnfjörð Bjarmason]

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.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/config.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 32f065c..f30d52a 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -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

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

[Johan Herland]

On Thu, Oct 6, 2016 at 10:49 AM, Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
> 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.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>

Acked-by: Johan Herland <johan@herland.net>


-- 
Johan Herland, <johan@herland.net>
www.herland.net

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

[Matthieu Moy]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

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

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.

> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -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.

Nit: I think the doc normally doesn't use "we" this way (we = the Git
developers or the Git tool). Hence my s/which we still support/still
supported/ above.

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

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

[Ævar Arnfjörð Bjarmason]

On Thu, Oct 6, 2016 at 2:13 PM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Ęvar Arnfjörš Bjarmason <avarab@gmail.com> writes:
>
>> That's bad, either we shouldn't support it at all, or we should
>> document what it does. This patch does the latter.
>
> 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.

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)?

>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -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.
>
> Nit: I think the doc normally doesn't use "we" this way (we = the Git
> developers or the Git tool). Hence my s/which we still support/still
> supported/ above.
>
> --
> Matthieu Moy
> http://www-verimag.imag.fr/~moy/

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

[Matthieu Moy]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> 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:
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -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/

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

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> 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:
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -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.

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/7vip6dgmx2.fsf@alter.siamese.dyndns.org/

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.

[PATCH v2] push: Re-include "push.default=tracking" in the documentation

[Ævar Arnfjörð Bjarmason]

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.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---

On Thu, Oct 6, 2016 at 8:24 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Sorry, I wasn't paying attention to this thread.

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

> 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/7vip6dgmx2.fsf@alter.siamese.dyndns.org/
>
> 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.

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(+)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index eccc012672..988659e16c 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -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

Re: [PATCH v2] push: Re-include "push.default=tracking" in the documentation

[Junio C Hamano]

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index eccc012672..988659e16c 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -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.

Thanks for following through ;-)  Will queue.