* [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules @ 2016-05-04 22:40 Stefan Beller 2016-05-04 23:08 ` Junio C Hamano 2016-05-04 23:26 ` Jonathan Nieder 0 siblings, 2 replies; 11+ messages in thread From: Stefan Beller @ 2016-05-04 22:40 UTC (permalink / raw) To: gitster; +Cc: git, jrnieder, Jens.Lehmann, Stefan Beller The discussion in [1] pointed out that '.' is a faulty suggestion as there is a corner case where it fails: > "submodule deinit ." may have "worked" in the sense that you would > have at least one path in your tree and avoided this "nothing > matches" most of the time. It would have still failed with the > exactly same error if run in an empty repository, i.e. > > $ E=/var/tmp/x/empty && rm -fr "$E" && mkdir -p "$E" && cd "$E" > $ git init > $ rungit v2.6.6 submodule deinit . > error: pathspec '.' did not match any file(s) known to git. > Did you forget to 'git add'? > $ >file && git add file > $ rungit v2.6.6 submodule deinit . > $ echo $? > 0 So instead of a pathspec add the '--all' option to deinit all submodules and add a test to check for the corner case of an empty repository. The code only needs to learn about the '--all' option and doesn't require further changes as `git submodule--helper list "$@"` will list all submodules when "$@" is empty. [1] http://news.gmane.org/gmane.comp.version-control.git/289535 Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Stefan Beller <sbeller@google.com> --- * reworded commit message slightly (realize, pathspec) * reworded the documentation * no "usage:" to go thru l10n. Documentation/git-submodule.txt | 25 +++++++++++++++++++------ git-submodule.sh | 14 +++++++++++--- t/t7400-submodule-basic.sh | 28 +++++++++++++++++++++++++++- 3 files changed, 57 insertions(+), 10 deletions(-) diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 1572f05..aeeb2ed 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -13,7 +13,7 @@ SYNOPSIS [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] -'git submodule' [--quiet] deinit [-f|--force] [--] <path>... +'git submodule' [--quiet] deinit [-f|--force] (-a|--all|[--] <path>...) 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--] [<path>...] @@ -140,12 +140,20 @@ deinit:: tree. Further calls to `git submodule update`, `git submodule foreach` and `git submodule sync` will skip any unregistered submodules until they are initialized again, so use this command if you don't want to - have a local checkout of the submodule in your work tree anymore. If + have a local checkout of the submodule in your working tree anymore. If you really want to remove a submodule from the repository and commit that use linkgit:git-rm[1] instead. + -If `--force` is specified, the submodule's work tree will be removed even if -it contains local modifications. +When the command is run without pathspec, it errors out, +instead of deinit-ing everything, to prevent mistakes. In +version 2.8 and before the command gave a suggestion to use +'.' to unregister all submodules when it was invoked without +any argument, but this suggestion did not work and gave a +wrong message if you followed it in pathological cases and is +no longer recommended. ++ +If `--force` is specified, the submodule's working tree will +be removed even if it contains local modifications. update:: + @@ -247,6 +255,11 @@ OPTIONS --quiet:: Only print error messages. +-a:: +--all:: + This option is only valid for the deinit command. Unregister all + submodules in the working tree. + -b:: --branch:: Branch of repository to add as submodule. @@ -257,8 +270,8 @@ OPTIONS --force:: This option is only valid for add, deinit and update commands. When running add, allow adding an otherwise ignored submodule path. - When running deinit the submodule work trees will be removed even if - they contain local changes. + When running deinit the submodule working trees will be removed even + if they contain local changes. When running update (only effective with the checkout procedure), throw away local changes in submodules when switching to a different commit; and always run a checkout operation in the diff --git a/git-submodule.sh b/git-submodule.sh index 43c68de..caa80fe 100755 --- a/git-submodule.sh +++ b/git-submodule.sh @@ -8,7 +8,7 @@ dashless=$(basename "$0" | sed -e 's/-/ /') USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>] or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...] or: $dashless [--quiet] init [--] [<path>...] - or: $dashless [--quiet] deinit [-f|--force] [--] <path>... + or: $dashless [--quiet] deinit [-f|--force] (-a|--all| [--] <path>...) or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] [--recursive] [--] [<path>...] or: $dashless [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...] or: $dashless [--quiet] foreach [--recursive] <command> @@ -521,6 +521,7 @@ cmd_init() cmd_deinit() { # parse $args after "submodule ... deinit". + deinit_all= while test $# -ne 0 do case "$1" in @@ -530,6 +531,9 @@ cmd_deinit() -q|--quiet) GIT_QUIET=1 ;; + -a|--all) + deinit_all=t + ;; --) shift break @@ -544,9 +548,13 @@ cmd_deinit() shift done - if test $# = 0 + if test -n "$deinit_all" && test "$#" -ne 0 + then + die "$(eval_gettext "--all and pathspec are incompatible")" + fi + if test $# = 0 && test -z "$deinit_all" then - die "$(eval_gettext "Use '.' if you really want to deinitialize all submodules")" + die "$(eval_gettext "Use '--all' if you really want to deinitialize all submodules")" fi git submodule--helper list --prefix "$wt_prefix" "$@" | diff --git a/t/t7400-submodule-basic.sh b/t/t7400-submodule-basic.sh index e1abd19..bd0d229 100755 --- a/t/t7400-submodule-basic.sh +++ b/t/t7400-submodule-basic.sh @@ -11,6 +11,10 @@ subcommands of git submodule. . ./test-lib.sh +test_expect_success 'submodule deinit works on empty repository' ' + git submodule deinit --all +' + test_expect_success 'setup - initial commit' ' >t && git add t && @@ -858,7 +862,8 @@ test_expect_success 'submodule deinit works on repository without submodules' ' >file && git add file && git commit -m "repo should not be empty" - git submodule deinit . + git submodule deinit . && + git submodule deinit --all ) ' @@ -900,6 +905,19 @@ test_expect_success 'submodule deinit . deinits all initialized submodules' ' rmdir init example2 ' +test_expect_success 'submodule deinit --all deinits all initialized submodules' ' + git submodule update --init && + git config submodule.example.foo bar && + git config submodule.example2.frotz nitfol && + test_must_fail git submodule deinit && + git submodule deinit --all >actual && + test -z "$(git config --get-regexp "submodule\.example\.")" && + test -z "$(git config --get-regexp "submodule\.example2\.")" && + test_i18ngrep "Cleared directory .init" actual && + test_i18ngrep "Cleared directory .example2" actual && + rmdir init example2 +' + test_expect_success 'submodule deinit deinits a submodule when its work tree is missing or empty' ' git submodule update --init && rm -rf init example2/* example2/.git && @@ -966,6 +984,14 @@ test_expect_success 'submodule deinit is silent when used on an uninitialized su test_i18ngrep ! "Submodule .example. (.*) unregistered for path .init" actual && test_i18ngrep ! "Submodule .example2. (.*) unregistered for path .example2" actual && test_i18ngrep "Cleared directory .init" actual && + git submodule deinit --all >actual && + test_i18ngrep ! "Submodule .example. (.*) unregistered for path .init" actual && + test_i18ngrep "Submodule .example2. (.*) unregistered for path .example2" actual && + test_i18ngrep "Cleared directory .init" actual && + git submodule deinit -a >actual && + test_i18ngrep ! "Submodule .example. (.*) unregistered for path .init" actual && + test_i18ngrep ! "Submodule .example2. (.*) unregistered for path .example2" actual && + test_i18ngrep "Cleared directory .init" actual && rmdir init example2 ' -- 2.8.0.rc4.9.g082ee08.dirty ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-04 22:40 [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules Stefan Beller @ 2016-05-04 23:08 ` Junio C Hamano 2016-05-04 23:26 ` Jonathan Nieder 1 sibling, 0 replies; 11+ messages in thread From: Junio C Hamano @ 2016-05-04 23:08 UTC (permalink / raw) To: Stefan Beller; +Cc: git, jrnieder, Jens.Lehmann Stefan Beller <sbeller@google.com> writes: > +When the command is run without pathspec, it errors out, > +instead of deinit-ing everything, to prevent mistakes. In > +version 2.8 and before the command gave a suggestion to use > +'.' to unregister all submodules when it was invoked without > +any argument, but this suggestion did not work and gave a > +wrong message if you followed it in pathological cases and is > +no longer recommended. Thanks for noticing and fixing my typo ;-) I read everything again and it all looks good. Thanks. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-04 22:40 [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules Stefan Beller 2016-05-04 23:08 ` Junio C Hamano @ 2016-05-04 23:26 ` Jonathan Nieder 2016-05-04 23:38 ` Stefan Beller 1 sibling, 1 reply; 11+ messages in thread From: Jonathan Nieder @ 2016-05-04 23:26 UTC (permalink / raw) To: Stefan Beller; +Cc: gitster, git, Jens.Lehmann Hi, Stefan Beller wrote: > Signed-off-by: Stefan Beller <sbeller@google.com> > --- > * reworded commit message slightly (realize, pathspec) > * reworded the documentation Yay, thanks for your work on this. [...] > +++ b/Documentation/git-submodule.txt > @@ -13,7 +13,7 @@ SYNOPSIS > [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] > 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] > 'git submodule' [--quiet] init [--] [<path>...] > -'git submodule' [--quiet] deinit [-f|--force] [--] <path>... > +'git submodule' [--quiet] deinit [-f|--force] (-a|--all|[--] <path>...) > 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] > [-f|--force] [--rebase|--merge] [--reference <repository>] > [--depth <depth>] [--recursive] [--] [<path>...] > @@ -140,12 +140,20 @@ deinit:: > tree. Further calls to `git submodule update`, `git submodule foreach` > and `git submodule sync` will skip any unregistered submodules until > they are initialized again, so use this command if you don't want to > - have a local checkout of the submodule in your work tree anymore. If > + have a local checkout of the submodule in your working tree anymore. If > you really want to remove a submodule from the repository and commit > that use linkgit:git-rm[1] instead. > ++ > +When the command is run without pathspec, it errors out, > +instead of deinit-ing everything, to prevent mistakes. In > +version 2.8 and before the command gave a suggestion to use > +'.' to unregister all submodules when it was invoked without > +any argument, but this suggestion did not work and gave a > +wrong message if you followed it in pathological cases and is > +no longer recommended. Why tell the user what happened in 2.8 and earlier? It's not clear what the reader would do with that information. I think this paragraph could be removed. --all is explained lower down and the error message points it out to users who need it. > + > -If `--force` is specified, the submodule's work tree will be removed even if > -it contains local modifications. > +If `--force` is specified, the submodule's working tree will > +be removed even if it contains local modifications. (unnecessary rewrapping) [...] > update:: > + > @@ -247,6 +255,11 @@ OPTIONS > --quiet:: > Only print error messages. > > +-a:: > +--all:: > + This option is only valid for the deinit command. Unregister all > + submodules in the working tree. This could use an explanation of why I'd want to use it. E.g. This option is only valid for the deinit command. Unregister all submodules. Scripts should use this option instead of passing '.' to deinit because it works even in an empty repository with no submodules present. Not about this patch: the organization of options is a little strange. A separate section with options for each subcommand would be easier to read. Do we want to claim the short-and-sweet option -a? (I don't mind but it doesn't seem necessary.) [...] > @@ -257,8 +270,8 @@ OPTIONS > --force:: > This option is only valid for add, deinit and update commands. > When running add, allow adding an otherwise ignored submodule path. > - When running deinit the submodule work trees will be removed even if > - they contain local changes. > + When running deinit the submodule working trees will be removed even > + if they contain local changes. Unrelated change? [...] > @@ -544,9 +548,13 @@ cmd_deinit() > shift > done > > - if test $# = 0 > + if test -n "$deinit_all" && test "$#" -ne 0 > + then > + die "$(eval_gettext "--all and pathspec are incompatible")" This message still feels too low-level to me, but I might be swimming uphill here. Another option would be to call 'usage' and be done. [...] > --- a/t/t7400-submodule-basic.sh > +++ b/t/t7400-submodule-basic.sh Makes sense. In the context of the original motivation: this patch improves the advice printed by plain "git submodule deinit" but doesn't help with existing callers that might have run "git submodule deinit .". It might make sense to handle '.' as a historical special case in a separate patch. Thanks and sorry for all the complication, Jonathan ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-04 23:26 ` Jonathan Nieder @ 2016-05-04 23:38 ` Stefan Beller 2016-05-04 23:59 ` Jonathan Nieder 2016-05-05 17:59 ` Junio C Hamano 0 siblings, 2 replies; 11+ messages in thread From: Stefan Beller @ 2016-05-04 23:38 UTC (permalink / raw) To: Jonathan Nieder; +Cc: Junio C Hamano, git, Jens Lehmann On Wed, May 4, 2016 at 4:26 PM, Jonathan Nieder <jrnieder@gmail.com> wrote: > Hi, > > Stefan Beller wrote: > >> Signed-off-by: Stefan Beller <sbeller@google.com> >> --- >> * reworded commit message slightly (realize, pathspec) >> * reworded the documentation > > Yay, thanks for your work on this. > > [...] >> +++ b/Documentation/git-submodule.txt >> @@ -13,7 +13,7 @@ SYNOPSIS >> [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] >> 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] >> 'git submodule' [--quiet] init [--] [<path>...] >> -'git submodule' [--quiet] deinit [-f|--force] [--] <path>... >> +'git submodule' [--quiet] deinit [-f|--force] (-a|--all|[--] <path>...) >> 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] >> [-f|--force] [--rebase|--merge] [--reference <repository>] >> [--depth <depth>] [--recursive] [--] [<path>...] >> @@ -140,12 +140,20 @@ deinit:: >> tree. Further calls to `git submodule update`, `git submodule foreach` >> and `git submodule sync` will skip any unregistered submodules until >> they are initialized again, so use this command if you don't want to >> - have a local checkout of the submodule in your work tree anymore. If >> + have a local checkout of the submodule in your working tree anymore. If >> you really want to remove a submodule from the repository and commit >> that use linkgit:git-rm[1] instead. >> ++ >> +When the command is run without pathspec, it errors out, >> +instead of deinit-ing everything, to prevent mistakes. In >> +version 2.8 and before the command gave a suggestion to use >> +'.' to unregister all submodules when it was invoked without >> +any argument, but this suggestion did not work and gave a >> +wrong message if you followed it in pathological cases and is >> +no longer recommended. > > Why tell the user what happened in 2.8 and earlier? It's not clear what > the reader would do with that information. Because people may wonder what happened to '.' ? > > I think this paragraph could be removed. --all is explained lower > down and the error message points it out to users who need it. When we want to keep supporting '.' forever, I would remove this section. > >> + >> -If `--force` is specified, the submodule's work tree will be removed even if >> -it contains local modifications. >> +If `--force` is specified, the submodule's working tree will >> +be removed even if it contains local modifications. > > (unnecessary rewrapping) > > [...] >> update:: >> + >> @@ -247,6 +255,11 @@ OPTIONS >> --quiet:: >> Only print error messages. >> >> +-a:: >> +--all:: >> + This option is only valid for the deinit command. Unregister all >> + submodules in the working tree. > > This could use an explanation of why I'd want to use it. E.g. > > This option is only valid for the deinit command. Unregister all > submodules. Scripts should use this option instead of passing '.' > to deinit because it works even in an empty repository with no > submodules present. I would not want to mention '.' in the documentation. this can read: As a user I am fine to use '.' and then I wonder when it breaks. > > Not about this patch: the organization of options is a little strange. > A separate section with options for each subcommand would be easier to > read. I agree. > > Do we want to claim the short-and-sweet option -a? (I don't mind but it > doesn't seem necessary.) We do. > > [...] >> @@ -257,8 +270,8 @@ OPTIONS >> --force:: >> This option is only valid for add, deinit and update commands. >> When running add, allow adding an otherwise ignored submodule path. >> - When running deinit the submodule work trees will be removed even if >> - they contain local changes. >> + When running deinit the submodule working trees will be removed even >> + if they contain local changes. > > Unrelated change? It's close enough for deinit to squash it in here, no? > > [...] >> @@ -544,9 +548,13 @@ cmd_deinit() >> shift >> done >> >> - if test $# = 0 >> + if test -n "$deinit_all" && test "$#" -ne 0 >> + then >> + die "$(eval_gettext "--all and pathspec are incompatible")" > > This message still feels too low-level to me, but I might be swimming > uphill here. > > Another option would be to call 'usage' and be done. I had that idea as well, but I think pointing out the low level is better than giving the high level again, so the user immediately sees what's wrong. > > [...] >> --- a/t/t7400-submodule-basic.sh >> +++ b/t/t7400-submodule-basic.sh > > Makes sense. > > In the context of the original motivation: this patch improves the > advice printed by plain "git submodule deinit" but doesn't help with > existing callers that might have run "git submodule deinit .". It might > make sense to handle '.' as a historical special case in a separate > patch. Once we change how '.' is handled we can do that? > > Thanks and sorry for all the complication, > Jonathan ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-04 23:38 ` Stefan Beller @ 2016-05-04 23:59 ` Jonathan Nieder 2016-05-05 18:03 ` Junio C Hamano 2016-05-05 19:02 ` Stefan Beller 2016-05-05 17:59 ` Junio C Hamano 1 sibling, 2 replies; 11+ messages in thread From: Jonathan Nieder @ 2016-05-04 23:59 UTC (permalink / raw) To: Stefan Beller; +Cc: Junio C Hamano, git, Jens Lehmann Stefan Beller wrote: > On Wed, May 4, 2016 at 4:26 PM, Jonathan Nieder <jrnieder@gmail.com> wrote: >> I think this paragraph could be removed. --all is explained lower >> down and the error message points it out to users who need it. > > When we want to keep supporting '.' forever, I would remove this section. Yes, please. We can't remove something like that without a deprecation process that I don't think is worth it here. [...] >>> +-a:: >>> +--all:: >>> + This option is only valid for the deinit command. Unregister all >>> + submodules in the working tree. >> >> This could use an explanation of why I'd want to use it. E.g. >> >> This option is only valid for the deinit command. Unregister all >> submodules. Scripts should use this option instead of passing '.' >> to deinit because it works even in an empty repository with no >> submodules present. > > I would not want to mention '.' in the documentation. this can read: > > As a user I am fine to use '.' and then I wonder when it breaks. Sorry for the lack of clarity. By referencing scripts I was referring to "callers that want to be able to run the same command in all situations, even the edge case of no files present". I agree with you that humans should care just as much as scripts about things that will break and that we shouldn't break them. :) [...] >>> @@ -257,8 +270,8 @@ OPTIONS >>> --force:: >>> This option is only valid for add, deinit and update commands. >>> When running add, allow adding an otherwise ignored submodule path. >>> - When running deinit the submodule work trees will be removed even if >>> - they contain local changes. >>> + When running deinit the submodule working trees will be removed even >>> + if they contain local changes. >> >> Unrelated change? > > It's close enough for deinit to squash it in here, no? My preference would be to have a separate patch since its commit message can explain the purpose. I don't care much --- it was just something I noticed while reviewing the rest. [...] >>> + if test -n "$deinit_all" && test "$#" -ne 0 >>> + then >>> + die "$(eval_gettext "--all and pathspec are incompatible")" >> >> This message still feels too low-level to me, but I might be swimming >> uphill here. >> >> Another option would be to call 'usage' and be done. > > I had that idea as well, but I think pointing out the low level is better > than giving the high level again, so the user immediately sees what's wrong. I mean low level as in implementation detail. The human user would wonder "what is incompatible about them? Why are you stopping me from what I am trying to do?" Most likely the user was trying to do something other than specify a path, since they also passed --all. If I run something like git submodule deinit force --all and the output tells me that --all and pathspec are incompatible then I just scratch my head more. We can do USAGE="$dashless [--quiet] deinit [-f|--force] (--all | [--] <path>...)" usage to print the subcommand's usage. git commandline tools don't translate any usage strings today, so not getting translation here wouldn't feel out of place. [...] >> In the context of the original motivation: this patch improves the >> advice printed by plain "git submodule deinit" but doesn't help with >> existing callers that might have run "git submodule deinit .". It might >> make sense to handle '.' as a historical special case in a separate >> patch. > > Once we change how '.' is handled we can do that? It's harmless even before then. Anyway, I meant "as a preparatory step before such a change that would otherwise be backward incompatible." Thanks, Jonathan ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-04 23:59 ` Jonathan Nieder @ 2016-05-05 18:03 ` Junio C Hamano 2016-05-05 19:20 ` Jonathan Nieder 2016-05-05 19:02 ` Stefan Beller 1 sibling, 1 reply; 11+ messages in thread From: Junio C Hamano @ 2016-05-05 18:03 UTC (permalink / raw) To: Jonathan Nieder; +Cc: Stefan Beller, git, Jens Lehmann Jonathan Nieder <jrnieder@gmail.com> writes: > I mean low level as in implementation detail. The human user would > wonder "what is incompatible about them? Why are you stopping me from > what I am trying to do?" Maybe s/incompatible/inconsistent/ is what you are after? Why are you stopping me from what I am trying to do? Because you are asking to do two contradicting things. Do you want to nuke everything, or do you want to keep everything outside what you specified? After being saved countless times from a stupid mistake $ git commit -a -s foo.c that was caused by habitually typing "-a", when I do want to limit the changes to record to a specific path (or two) with similar safety, I do not think "what is incompatible about them" is a valid question. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-05 18:03 ` Junio C Hamano @ 2016-05-05 19:20 ` Jonathan Nieder 2016-05-05 19:35 ` Stefan Beller 0 siblings, 1 reply; 11+ messages in thread From: Jonathan Nieder @ 2016-05-05 19:20 UTC (permalink / raw) To: Junio C Hamano; +Cc: Stefan Beller, git, Jens Lehmann Junio C Hamano wrote: > Jonathan Nieder <jrnieder@gmail.com> writes: >> I mean low level as in implementation detail. The human user would >> wonder "what is incompatible about them? Why are you stopping me from >> what I am trying to do?" > > Maybe s/incompatible/inconsistent/ is what you are after? Why are > you stopping me from what I am trying to do? Because you are asking > to do two contradicting things. Do you want to nuke everything, or > do you want to keep everything outside what you specified? > > After being saved countless times from a stupid mistake > > $ git commit -a -s foo.c > > that was caused by habitually typing "-a", when I do want to limit > the changes to record to a specific path (or two) with similar > safety, I do not think "what is incompatible about them" is a valid > question. Yes, 'inconsistent' works better than 'incompatible'. Stepping back, what I meant is that when I pass an invalid set of command line arguments, it's difficult to give advice back because it's not obvious what I intended to do. When I say "git submodule deinit --all -- foo/", I'm most likely trying to deinit all submodules within the foo subdirectory. That's a perfectly consistent thing to want --- it just doesn't match what the command is expecting. It is more helpful for the command to tell me what it is expecting me to do instead instead of just telling me that what I gave it is wrong. The ideal would be something like "git check-attr"'s error_with_usage. It tells in a targetted way where my error was and also gives a guide of what to do instead. $ git submodule deinit --all lib/ error: paths with --all do not make sense usage: git submodule deinit [-f | --force] (--all | [--] <path>...) Thanks, Jonathan -- >8 -- Subject: git-sh-setup: add error_with_usage helper When given an impossible set of options, this allows a command to print a targetted message followed by a short usage string that tells the user both (1) what part of their command wasn't supported (what went wrong) and (2) what correct usage looks like (what to do instead). Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> --- git-sh-setup.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/git-sh-setup.sh b/git-sh-setup.sh index c48139a..2b56636 100644 --- a/git-sh-setup.sh +++ b/git-sh-setup.sh @@ -63,6 +63,11 @@ say () { fi } +error_with_usage () { + printf >&2 'error: %s\n' "$*" + usage +} + if test -n "$OPTIONS_SPEC"; then usage() { "$0" -h -- ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-05 19:20 ` Jonathan Nieder @ 2016-05-05 19:35 ` Stefan Beller 0 siblings, 0 replies; 11+ messages in thread From: Stefan Beller @ 2016-05-05 19:35 UTC (permalink / raw) To: Jonathan Nieder; +Cc: Junio C Hamano, git, Jens Lehmann On Thu, May 5, 2016 at 12:20 PM, Jonathan Nieder <jrnieder@gmail.com> wrote: > Junio C Hamano wrote: >> Jonathan Nieder <jrnieder@gmail.com> writes: > >>> I mean low level as in implementation detail. The human user would >>> wonder "what is incompatible about them? Why are you stopping me from >>> what I am trying to do?" >> >> Maybe s/incompatible/inconsistent/ is what you are after? Why are >> you stopping me from what I am trying to do? Because you are asking >> to do two contradicting things. Do you want to nuke everything, or >> do you want to keep everything outside what you specified? >> >> After being saved countless times from a stupid mistake >> >> $ git commit -a -s foo.c >> >> that was caused by habitually typing "-a", when I do want to limit >> the changes to record to a specific path (or two) with similar >> safety, I do not think "what is incompatible about them" is a valid >> question. > > Yes, 'inconsistent' works better than 'incompatible'. Stepping back, > what I meant is that when I pass an invalid set of command line > arguments, it's difficult to give advice back because it's not obvious > what I intended to do. > > When I say "git submodule deinit --all -- foo/", I'm most likely trying > to deinit all submodules within the foo subdirectory. That's a > perfectly consistent thing to want --- it just doesn't match what the > command is expecting. It is more helpful for the command to tell me > what it is expecting me to do instead instead of just telling me that what > I gave it is wrong. > > The ideal would be something like "git check-attr"'s error_with_usage. > It tells in a targetted way where my error was and also gives a guide > of what to do instead. > > $ git submodule deinit --all lib/ > error: paths with --all do not make sense > usage: git submodule deinit [-f | --force] (--all | [--] <path>...) > > Thanks, > Jonathan > > -- >8 -- > Subject: git-sh-setup: add error_with_usage helper > > When given an impossible set of options, this allows a command to > print a targetted message followed by a short usage string that tells > the user both (1) what part of their command wasn't supported (what > went wrong) and (2) what correct usage looks like (what to do > instead). > > Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Thanks for this patch, I can take that as a preparation for the patch under discussion. > --- > git-sh-setup.sh | 5 +++++ > 1 file changed, 5 insertions(+) > > diff --git a/git-sh-setup.sh b/git-sh-setup.sh > index c48139a..2b56636 100644 > --- a/git-sh-setup.sh > +++ b/git-sh-setup.sh > @@ -63,6 +63,11 @@ say () { > fi > } > > +error_with_usage () { As usage is the last thing (it's die(...) essentially), I'd rename it to die_with_usage ? > + printf >&2 'error: %s\n' "$*" > + usage > +} > + > if test -n "$OPTIONS_SPEC"; then > usage() { > "$0" -h > -- ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-04 23:59 ` Jonathan Nieder 2016-05-05 18:03 ` Junio C Hamano @ 2016-05-05 19:02 ` Stefan Beller 1 sibling, 0 replies; 11+ messages in thread From: Stefan Beller @ 2016-05-05 19:02 UTC (permalink / raw) To: Jonathan Nieder; +Cc: Junio C Hamano, git, Jens Lehmann On Wed, May 4, 2016 at 4:59 PM, Jonathan Nieder <jrnieder@gmail.com> wrote: >>> >>> Another option would be to call 'usage' and be done. >> >> I had that idea as well, but I think pointing out the low level is better >> than giving the high level again, so the user immediately sees what's wrong. > > I mean low level as in implementation detail. The human user would > wonder "what is incompatible about them? Why are you stopping me from > what I am trying to do?" Most likely the user was trying to do > something other than specify a path, since they also passed --all. If > I run something like > > $ git submodule deinit force --all error: unknown option `all' usage: git submodule--helper list [--prefix=<path>] [<path>...] --prefix <path> alternative anchor for relative paths `force` is seen as the first pathspec, so "force --all" is given to the `submodule--helper list`, which gives a less than optimal error message $ git submodule deinit --all force gettext: unrecognized option '--all and pathspec are incompatible' Try 'gettext --help' for more information. envsubst: unrecognized option '--all and pathspec are incompatible' Try 'envsubst --help' for more information. envsubst: unrecognized option '--all and pathspec are incompatible' Try 'envsubst --help' for more information. We should not put --all as the first thing in the error message. $ git submodule deinit --all force pathspec and --all are incompatible With the next patch this is the error message. I think the missing dashes for force are quite visible as force is after --all. > > and the output tells me that --all and pathspec are incompatible then > I just scratch my head more. > > We can do > > USAGE="$dashless [--quiet] deinit [-f|--force] (--all | [--] <path>...)" > usage > > to print the subcommand's usage. git commandline tools don't > translate any usage strings today, so not getting translation here > wouldn't feel out of place. We can have both? I'd prefer not rewriting the USAGE string here as it would easily be out of sync in the future? I tried to just grep the deinit line from the USAGe though, but that doesn't look right as it would need some post processing. (remove the "or:") and processing the USAGE string also doesn't sound future proof. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-04 23:38 ` Stefan Beller 2016-05-04 23:59 ` Jonathan Nieder @ 2016-05-05 17:59 ` Junio C Hamano 2016-05-05 18:11 ` Stefan Beller 1 sibling, 1 reply; 11+ messages in thread From: Junio C Hamano @ 2016-05-05 17:59 UTC (permalink / raw) To: Stefan Beller; +Cc: Jonathan Nieder, git, Jens Lehmann Stefan Beller <sbeller@google.com> writes: >>> +When the command is run without pathspec, it errors out, >>> +instead of deinit-ing everything, to prevent mistakes. In >>> +version 2.8 and before the command gave a suggestion to use >>> +'.' to unregister all submodules when it was invoked without >>> +any argument, but this suggestion did not work and gave a >>> +wrong message if you followed it in pathological cases and is >>> +no longer recommended. >> >> Why tell the user what happened in 2.8 and earlier? It's not clear what >> the reader would do with that information. > > Because people may wonder what happened to '.' ? I am to blame on that final text, but I think Jonathan is right. "In version 2.8 and earlier..." can just go. Users may need to understand why no-arg form is not a silent no-op but an error, and they need to know how to de-init everything with the version of Git they have (i.e. with "--all"). Compared to these two, "Your fingers may have been trained to say '.', but it was found not to work in pathological cases" is of much lessor importance, especially because with or without this patch, the definition of "pathological" cases does not change. >> I think this paragraph could be removed. --all is explained lower >> down and the error message points it out to users who need it. > > When we want to keep supporting '.' forever, I would remove this section. I am not sure what you mean by "keep supporting '.'". If your repository has any tracked path, "deinit ." would deinit all submodules, with or without this change. Are you worried about the future change you are planning to that involves reverting 84ba959b (submodule: fix regression for deinit without submodules, 2016-03-22), after which a pathspec that does not match any submodule would become a "possible typo" error? It is true that '.' would error out if there is no submodule in the repository, as opposed to erroring out only when there is no tracked path, which is what you get with today's version (and the version with this fix in the patch under discussion). But '.' is not special with respect to that change. 'README' would also error out if there is no submodule whose path matches that pathspec in that future version, as opposed to erroring out only if 'README' is not tracked at all in today's version. Or are you thinking that it may be better to give '.' a special meaning, iow, not treating it as just a regular pathspec? Perhaps make '.' to mean "everything but it is not an error if there is none to begin with"? I fear that going in that direction would deform the mental model the users would form from seeing how commands behave when given a pathspec. The "." would still look like any other pathspec elements, and I am sure you will not special case "." in the usage string but will claim that it is covered by the mention of <pathspec> at the end of the command line in the usage string, so you are making them expect that "." used as a pathspec would behave like that for all other places that we take pathspec, when in reality, only "submodule deinit" make it behave differently. Which I do not think is particularly a good idea. >> Not about this patch: the organization of options is a little strange. >> A separate section with options for each subcommand would be easier to >> read. > > I agree. I agree. >> Do we want to claim the short-and-sweet option -a? (I don't mind but it >> doesn't seem necessary.) > > We do. I don't, but I do not care too deeaply. >>> @@ -257,8 +270,8 @@ OPTIONS >>> --force:: >>> This option is only valid for add, deinit and update commands. >>> When running add, allow adding an otherwise ignored submodule path. >>> - When running deinit the submodule work trees will be removed even if >>> - they contain local changes. >>> + When running deinit the submodule working trees will be removed even >>> + if they contain local changes. >> >> Unrelated change? > > It's close enough for deinit to squash it in here, no? More importantly, the patch adds a new instance of "working tree" to the documentation elsewhere; fixing this existing instance of "work tree" is relevant from consistency's point of view. >>> @@ -544,9 +548,13 @@ cmd_deinit() >>> shift >>> done >>> >>> - if test $# = 0 >>> + if test -n "$deinit_all" && test "$#" -ne 0 >>> + then >>> + die "$(eval_gettext "--all and pathspec are incompatible")" >> >> This message still feels too low-level to me, but I might be swimming >> uphill here. >> >> Another option would be to call 'usage' and be done. > > I had that idea as well, but I think pointing out the low level is better > than giving the high level again, so the user immediately sees what's wrong. I do not particularly see the message low-level. Jonathan, what do you have against pointing out the exact problem? After seeing the usage string that also talks about --quite, --force, etc., I have to somehow realize that these are irrelevant noises that have nothing to do with the error, and puzzle out that the (choose|from|here) is telling me that I cannot give pathspec when I am giving --all myself. > Once we change how '.' is handled we can do that? Again, I am worried about "Once we change how ...". ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules 2016-05-05 17:59 ` Junio C Hamano @ 2016-05-05 18:11 ` Stefan Beller 0 siblings, 0 replies; 11+ messages in thread From: Stefan Beller @ 2016-05-05 18:11 UTC (permalink / raw) To: Junio C Hamano; +Cc: Jonathan Nieder, git, Jens Lehmann On Thu, May 5, 2016 at 10:59 AM, Junio C Hamano <gitster@pobox.com> wrote: > Stefan Beller <sbeller@google.com> writes: > >>>> +When the command is run without pathspec, it errors out, >>>> +instead of deinit-ing everything, to prevent mistakes. In >>>> +version 2.8 and before the command gave a suggestion to use >>>> +'.' to unregister all submodules when it was invoked without >>>> +any argument, but this suggestion did not work and gave a >>>> +wrong message if you followed it in pathological cases and is >>>> +no longer recommended. >>> >>> Why tell the user what happened in 2.8 and earlier? It's not clear what >>> the reader would do with that information. >> >> Because people may wonder what happened to '.' ? > > I am to blame on that final text, but I think Jonathan is right. > "In version 2.8 and earlier..." can just go. Users may need to > understand why no-arg form is not a silent no-op but an error, > and they need to know how to de-init everything with the version > of Git they have (i.e. with "--all"). Compared to these two, > "Your fingers may have been trained to say '.', but it was found > not to work in pathological cases" is of much lessor importance, > especially because with or without this patch, the definition of > "pathological" cases does not change. So we'll only give When the command is run without pathspec, it errors out, instead of deinit-ing everything, to prevent mistakes. > >>> I think this paragraph could be removed. --all is explained lower >>> down and the error message points it out to users who need it. >> >> When we want to keep supporting '.' forever, I would remove this section. > > I am not sure what you mean by "keep supporting '.'". If your > repository has any tracked path, "deinit ." would deinit all > submodules, with or without this change. > > Are you worried about the future change you are planning to that > involves reverting 84ba959b (submodule: fix regression for deinit > without submodules, 2016-03-22), after which a pathspec that does > not match any submodule would become a "possible typo" error? When redoing the groups series, I may or may not go that route. It sounds compelling to me. > > It is true that '.' would error out if there is no submodule in the > repository, as opposed to erroring out only when there is no tracked > path, which is what you get with today's version (and the version > with this fix in the patch under discussion). But '.' is not > special with respect to that change. 'README' would also error out > if there is no submodule whose path matches that pathspec in that > future version, as opposed to erroring out only if 'README' is not > tracked at all in today's version. > > Or are you thinking that it may be better to give '.' a special > meaning, iow, not treating it as just a regular pathspec? Perhaps > make '.' to mean "everything but it is not an error if there is none > to begin with"? I fear that going in that direction would deform > the mental model the users would form from seeing how commands > behave when given a pathspec. The "." would still look like any > other pathspec elements, and I am sure you will not special case "." > in the usage string but will claim that it is covered by the mention > of <pathspec> at the end of the command line in the usage string, > so you are making them expect that "." used as a pathspec would > behave like that for all other places that we take pathspec, when > in reality, only "submodule deinit" make it behave differently. > > Which I do not think is particularly a good idea. I did not think special casing '.'. (I did in the very first patch, but I understand that it's a bad idea now, so I do not think of it again) > >>> Not about this patch: the organization of options is a little strange. >>> A separate section with options for each subcommand would be easier to >>> read. >> >> I agree. > > I agree. > >>> Do we want to claim the short-and-sweet option -a? (I don't mind but it >>> doesn't seem necessary.) >> >> We do. > > I don't, but I do not care too deeaply. Me neither, so I'll remove the short option. > > >>>> @@ -257,8 +270,8 @@ OPTIONS >>>> --force:: >>>> This option is only valid for add, deinit and update commands. >>>> When running add, allow adding an otherwise ignored submodule path. >>>> - When running deinit the submodule work trees will be removed even if >>>> - they contain local changes. >>>> + When running deinit the submodule working trees will be removed even >>>> + if they contain local changes. >>> >>> Unrelated change? >> >> It's close enough for deinit to squash it in here, no? > > More importantly, the patch adds a new instance of "working tree" to > the documentation elsewhere; fixing this existing instance of "work > tree" is relevant from consistency's point of view. > >>>> @@ -544,9 +548,13 @@ cmd_deinit() >>>> shift >>>> done >>>> >>>> - if test $# = 0 >>>> + if test -n "$deinit_all" && test "$#" -ne 0 >>>> + then >>>> + die "$(eval_gettext "--all and pathspec are incompatible")" >>> >>> This message still feels too low-level to me, but I might be swimming >>> uphill here. >>> >>> Another option would be to call 'usage' and be done. >> >> I had that idea as well, but I think pointing out the low level is better >> than giving the high level again, so the user immediately sees what's wrong. > > I do not particularly see the message low-level. Jonathan, what do > you have against pointing out the exact problem? After seeing the > usage string that also talks about --quite, --force, etc., I have to > somehow realize that these are irrelevant noises that have nothing > to do with the error, and puzzle out that the (choose|from|here) is > telling me that I cannot give pathspec when I am giving --all > myself. > >> Once we change how '.' is handled we can do that? > > Again, I am worried about "Once we change how ...". By that I mainly mean reverting 84ba959b (submodule: fix regression for deinit without submodules, 2016-03-22), but I am aware that this is a major change as it breaks existing users. Thanks, Stefan ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2016-05-05 19:35 UTC | newest] Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2016-05-04 22:40 [PATCHv4] submodule deinit: require '--all' instead of '.' for all submodules Stefan Beller 2016-05-04 23:08 ` Junio C Hamano 2016-05-04 23:26 ` Jonathan Nieder 2016-05-04 23:38 ` Stefan Beller 2016-05-04 23:59 ` Jonathan Nieder 2016-05-05 18:03 ` Junio C Hamano 2016-05-05 19:20 ` Jonathan Nieder 2016-05-05 19:35 ` Stefan Beller 2016-05-05 19:02 ` Stefan Beller 2016-05-05 17:59 ` Junio C Hamano 2016-05-05 18:11 ` Stefan Beller
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.