Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
On Mon, Apr 23, 2012 at 10:37 AM, Matthieu Moy matthieu@imag.fr wrote: It's been deprecated since 53c4031 (Johan Herland, Wed Feb 16 2011, push.default: Rename 'tracking' to 'upstream'), so it's OK to remove it from documentation (even though it's still supported) to make the explanations more readable. I don't think this was a good move for the documentation. Now every time I find an old repo with push.default=tracking I end up wondering what it was a synonym for again, and other users who don't know what it does will just assume it's an invalid value or something. We can't treat existing config values we still support as any other deprecated feature. They still exist in files we have no control over, and in people's brains who are reading man git-config trying to remember what it meant. Signed-off-by: Matthieu Moy matthieu@imag.fr --- Feel free to squash into previous one if needed. Documentation/config.txt |1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index e38fab1..ddf6043 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1693,7 +1693,6 @@ push.default:: makes `git push` and `git pull` symmetrical in the sense that `push` will update the same remote ref as the one which is merged by `git pull`. -* `tracking` - deprecated synonym for `upstream`. * `current` - push the current branch to a branch of the same name. + The `current` and `upstream` modes are for those who want to -- 1.7.10.234.ge65dd.dirty -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Ævar Arnfjörð Bjarmason ava...@gmail.com writes: On Mon, Apr 23, 2012 at 10:37 AM, Matthieu Moy matthieu@imag.fr wrote: It's been deprecated since 53c4031 (Johan Herland, Wed Feb 16 2011, push.default: Rename 'tracking' to 'upstream'), so it's OK to remove it from documentation (even though it's still supported) to make the explanations more readable. I don't think this was a good move for the documentation. Now every time I find an old repo with push.default=tracking I end up wondering what it was a synonym for again, and other users who don't know what it does will just assume it's an invalid value or something. We can't treat existing config values we still support as any other deprecated feature. They still exist in files we have no control over, and in people's brains who are reading man git-config trying to remember what it meant. 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. I think I can be persuaded to apply a patch that mentions 'tracking' as a side note. Thanks. Signed-off-by: Matthieu Moy matthieu@imag.fr --- Feel free to squash into previous one if needed. Documentation/config.txt |1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index e38fab1..ddf6043 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1693,7 +1693,6 @@ push.default:: makes `git push` and `git pull` symmetrical in the sense that `push` will update the same remote ref as the one which is merged by `git pull`. -* `tracking` - deprecated synonym for `upstream`. * `current` - push the current branch to a branch of the same name. + The `current` and `upstream` modes are for those who want to -- 1.7.10.234.ge65dd.dirty -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Hi, 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. Is the problem that deprecated is not precise enough? For example, would it make sense to say deprecated synonym for `upstream`. Will be dropped in git 2.1 or something like that? My two cents, Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Jonathan Nieder wrote: Is the problem that deprecated is not precise enough? For example, would it make sense to say deprecated synonym for `upstream`. Will be dropped in git 2.1 or something like that? Also, if we plan to remove support soon, we should start warning when this setting is encountered so people know to update their configuration. Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Jonathan Nieder jrnie...@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. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
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 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Jonathan Nieder jrnie...@gmail.com writes: Jonathan Nieder wrote: Is the problem that deprecated is not precise enough? For example, would it make sense to say deprecated synonym for `upstream`. Will be dropped in git 2.1 or something like that? Also, if we plan to remove support soon, we should start warning when this setting is encountered so people know to update their configuration. I do not think this even needs to be removed. We deprecate something for one of two reasons. One is when it was a bad idea to support it, and we would want to remove the support eventually. This needs a migration plan. The other is when there are better ways available but we do not want to break the old way. We still do not want to encourage the old way to new users. The change from 'upstream' from 'tracking' is the latter. The wording will confuse new users when they want to learn what 'tracking' as a concept is, and it is better spelt 'upstream'. But the breakage is not serious enough to warrant forcing an old timer who can explain these two concepts to newbies when needed to update his configuration files he is not planning to show to newbies. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Jonathan Nieder jrnie...@gmail.com writes: 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. I thought your example was that you saw pull.default = tracking and wondering what it is. Why do you need global search for tracking, not just near pull.default is described, in the first place? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Junio C Hamano wrote: 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. Until pre-1.7.4 versions of git fall out of use, I don't agree that the above is true. :( 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. How about the following? * `nothing` - ... * `matching` - ... * `upstream` - ... * `simple` - ... * `current` - ... For compatibility with ancient config files, the following synonym is also supported. Don't use it. * `tracking` - old name for `upstream` -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Jonathan Nieder jrnie...@gmail.com writes: How about the following? * `nothing` - ... * `matching` - ... * `upstream` - ... * `simple` - ... * `current` - ... For compatibility with ancient config files, the following synonym is also supported. Don't use it. * `tracking` - old name for `upstream` Sounds good to me. I'm the author of the removal patch, but the patch was just part of a larger serie explaining push.default, the idea of cleaning up the obsolete alias came in the discussion and I did it, but I'm fine with reintroducing it in the doc (as long as it does not disturb new users too much). -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Junio C Hamano wrote: Jonathan Nieder jrnie...@gmail.com writes: 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. I thought your example was that you saw pull.default = tracking and wondering what it is. Why do you need global search for tracking, not just near pull.default is described, in the first place? Because the UI for local searches in web browsers and man pagers is seriously lacking. Or, because people have bad habits and do not take apppropriate advantage of search in small subsections of a document. All I know is that I have seen myself and others doing searches analagous to --print and not seen searches analagous to tracking. Am I really the only one that doesn't see the --print change as hiding an option and sees burying tracking in the text as qualitatively different? Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Jonathan Nieder jrnie...@gmail.com writes: Junio C Hamano wrote: 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. Until pre-1.7.4 versions of git fall out of use, I don't agree that the above is true. :( The documentation ships with the version that the above is true. We are not making an update to documentation that comes with ancient versions. 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. How about the following? * `nothing` - ... * `matching` - ... * `upstream` - ... * `simple` - ... * `current` - ... For compatibility with ancient config files, the following synonym is also supported. Don't use it. * `tracking` - old name for `upstream` Didn't I say I am fine to mention it as a side note in the original message you started responding to? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
From: Jonathan Nieder jrnie...@gmail.com Sent: Thursday, January 31, 2013 8:04 PM Junio C Hamano wrote: 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. Until pre-1.7.4 versions of git fall out of use, I don't agree that the above is true. :( 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`. From a simple user perspective, I'd simply place it, in brackets and at the end of the list. e.g. [* `tracking` - deprecated synonym for `upstream`.] The leading bracket makes it obvious that it's different, and that the description needs to be read, rather than folk simply re-using a half remembered option, gleaned from an old blog. However formatting the leading bracket may not be as easy as the plain text version. * `current` - push the current branch to a branch of the same name. How about the following? * `nothing` - ... * `matching` - ... * `upstream` - ... * `simple` - ... * `current` - ... For compatibility with ancient config files, the following synonym is also supported. Don't use it. * `tracking` - old name for `upstream` ? s/old/deprecated/ or s/old/outdated/ for those who don't understand the jargon. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Jonathan Nieder jrnie...@gmail.com writes: Am I really the only one that doesn't see the --print change as hiding an option and sees burying tracking in the text as qualitatively different? Sorry, but I do not understand the question. We are hiding/burying the --print option to make it clear that it is not a member with the same footing as others belonging to the group of options to the command. It is accepted, but there is no reason for the user to choose it over --normalize. We want to make sure that tracking does not appear as if it is a member of the pull.default set with equal rights as others. It is accepted, but there is no reason for the user to choose it over upstream. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Junio C Hamano gits...@pobox.com writes: Jonathan Nieder jrnie...@gmail.com writes: Am I really the only one that doesn't see the --print change as hiding an option and sees burying tracking in the text as qualitatively different? Sorry, but I do not understand the question. We are hiding/burying the --print option to make it clear that it is not a member with the same footing as others belonging to the group of options to the command. It is accepted, but there is no reason for the user to choose it over --normalize. We want to make sure that tracking does not appear as if it is a member of the pull.default set with equal rights as others. It is accepted, but there is no reason for the user to choose it over upstream. Now I re-read the proposed update, I think it is an improvement over a straight revert in that it makes it clear that 'tracking' does not belong, but I still think it is better to make it a sidenote to the 'upstream'. It makes the connection between the two stronger. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
How about doing it this way? I do not think anything that is deprecated even deserves a separate section and do not use it! heading. -- 8 -- When looking at a configuration file edited long time ago, a user may find 'pull.default = tracking' and wonder what it means. Instead of not mentioning it, add it to the description in a way that makes it clear that users have no reason to add new uses of it preferring over 'upstream'. Documentation/config.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index d7ec507..8441050 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1795,7 +1795,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). With this, `git push` will update the same remote ref as the one which is merged by `git pull`, making `push` and `pull` symmetrical. See branch.name.merge for how to configure the upstream branch. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Junio C Hamano wrote: How about doing it this way? [...] --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1795,7 +1795,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 have already explained that I believe this is a bad idea and why and proposed an alternative. I take it that either we are miscommunicating or we fundamentally disagree about the role of documentation. :( -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Junio C Hamano wrote: Jonathan Nieder jrnie...@gmail.com writes: Junio C Hamano wrote: 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. Until pre-1.7.4 versions of git fall out of use, I don't agree that the above is true. :( The documentation ships with the version that the above is true. We are not making an update to documentation that comes with ancient versions. Part of the context that I should have mentioned but didn't is that it is common to put $HOME on a shared filesystem. [...] How about the following? * `nothing` - ... * `matching` - ... * `upstream` - ... * `simple` - ... * `current` - ... For compatibility with ancient config files, the following synonym is also supported. Don't use it. * `tracking` - old name for `upstream` Didn't I say I am fine to mention it as a side note in the original message you started responding to? Yes, I understood what you were proposing and I directly disagreed with it and explained why. The above is something like a compromise --- more precisely, it is an attempt to do something better than a straight revert and to understand whether it would address your objection. Clearly it doesn't. I don't understand why. Perhaps the Don't use it is over the top and that is your complaint? It's true that if I were writing it without your objection in mind, I wouldn't have included that sentence. It was written on the assumption that you want to discourage people from using the tracking synonym --- I am not personally convinced that that is worth discouraging at all, but it's fine with me if the consensus is to do so. Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/7] Undocument deprecated alias 'push.default=tracking'
Jonathan Nieder jrnie...@gmail.com writes: [...] --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1795,7 +1795,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 have already explained that I believe this is a bad idea and why and proposed an alternative. I take it that either we are miscommunicating or we fundamentally disagree about the role of documentation. :( Whatever. For tonight, I'll queue this version on 'pu' primarily because I do not want to think about it anymore today and because I do not want to see us forget that we have to fix this in some way, and this was the only one that I can simply git am on this topic. It is not because I want to say this is the version we are going to use, stfu! This topic does not even deserve such inter-developer tension, IMHO. doc: mention tracking for pull.default When looking at a configuration file edited long time ago, a user may find 'pull.default = tracking' and wonder what it means, but earlier we stopped mentioning this value, even though the code still support it and more importantly, we have no intention to force old timers to update their configuration files. Instead of not mentioning it, add it to the description in a way that makes it clear that users have no reason to add new uses of it preferring over 'upstream', by not listing it as a separate item on the same footing as other values but as a deprecated synonym of the 'upstream' in its description. Signed-off-by: Junio C Hamano gits...@pobox.com -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
