{"thread":{"id":"35951","subject":"git submodule manpage does not document --checkout","startedAt":"2014-02-25T11:03:17Z","lastAt":"2014-02-28T22:41:11Z","messageCount":4,"participants":["Matthijs Kooijman","Jens Lehmann","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"235313","messageId":"20140225110316.GU11566@login.drsnuggles.stderr.nl","threadId":"35951","inReplyTo":null,"subject":"git submodule manpage does not document --checkout","fromName":"Matthijs Kooijman","fromEmail":"matthijs@stdin.nl","sentAt":"2014-02-25T11:03:17Z","receivedAt":"2014-02-25T11:03:17Z","isPatch":false,"sender":{"key":"matthijs@stdin.nl","avatar":"https://avatars.githubusercontent.com/u/194491?v=4"},"body":"Hi,\n\nit seems git submodule supports --checkout, which is also mentioned\nindirectly in the manpage. However, the option itself is not mentioned\nin the synopsis or detailed option list.\n\nGr.\n\nMatthijs\n"},{"id":"235516","messageId":"530FB5C4.8080400@web.de","threadId":"35951","inReplyTo":"20140225110316.GU11566@login.drsnuggles.stderr.nl","subject":"[PATCH] submodule update: document the '--checkout' option","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2014-02-27T22:01:40Z","receivedAt":"2014-02-27T22:01:40Z","isPatch":true,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Commit 322bb6e12f (add update 'none' flag to disable update of submodule\nby default) added the '--checkout' option to \"git submodule update\" but\nforgot to explicitly document it in the synopsis and the man page (It is\nonly mentioned implicitly in the man page).\n\nDocument this option in synopsis and man page too. While at it make it\nmore clear that only one of '--checkout', '--merge' or '--rebase' make\nsense by grouping them together.\n\nReported-by: Matthijs Kooijman <matthijs@stdin.nl>\nSigned-off-by: Jens Lehmann <Jens.Lehmann@web.de>\n---\n\nAm 25.02.2014 11:03, schrieb Matthijs Kooijman:\n> it seems git submodule supports --checkout, which is also mentioned\n> indirectly in the manpage. However, the option itself is not mentioned\n> in the synopsis or detailed option list.\n\nGood point. What about this?\n\n\n Documentation/git-submodule.txt | 13 +++++++++++--\n git-submodule.sh                |  2 +-\n 2 files changed, 12 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex bfef8a0..9054217 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -15,8 +15,8 @@ SYNOPSIS\n 'git submodule' [--quiet] init [--] [<path>...]\n 'git submodule' [--quiet] deinit [-f|--force] [--] <path>...\n 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]\n-\t      [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]\n-\t      [--merge] [--recursive] [--] [<path>...]\n+\t      [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>]\n+\t      [--depth <depth>] [--recursive] [--] [<path>...]\n 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]\n \t      [commit] [--] [<path>...]\n 'git submodule' [--quiet] foreach [--recursive] <command>\n@@ -287,6 +287,15 @@ SHA-1.  If you don't want to fetch, you should use `submodule update\n \tThis option is only valid for the update command.\n \tDon't fetch new objects from the remote site.\n\n+--checkout::\n+\tThis option is only valid for the update command.\n+\tCheckout the commit recorded in the superproject on a detached HEAD\n+\tin the submodule. This is the default behavior, the main use of\n+\tthis option is to override `submodule.$name.update` when set to\n+\t`merge`, `rebase` or `none`.\n+\tIf the key `submodule.$name.update` is either not explicitly set or\n+\tset to `checkout`, this option is implicit.\n+\n --merge::\n \tThis option is only valid for the update command.\n \tMerge the commit recorded in the superproject into the current branch\ndiff --git a/git-submodule.sh b/git-submodule.sh\nindex 4a30087..65cf963 100755\n--- a/git-submodule.sh\n+++ b/git-submodule.sh\n@@ -9,7 +9,7 @@ USAGE=\"[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <re\n    or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...]\n    or: $dashless [--quiet] init [--] [<path>...]\n    or: $dashless [--quiet] deinit [-f|--force] [--] <path>...\n-   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...]\n+   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] [--recursive] [--] [<path>...]\n    or: $dashless [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]\n    or: $dashless [--quiet] foreach [--recursive] <command>\n    or: $dashless [--quiet] sync [--recursive] [--] [<path>...]\"\n-- \n1.8.3.1\n"},{"id":"235670","messageId":"xmqqbnxqudbf.fsf@gitster.dls.corp.google.com","threadId":"35951","inReplyTo":"530FB5C4.8080400@web.de","subject":"Re: [PATCH] submodule update: document the '--checkout' option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-02-28T21:39:32Z","receivedAt":"2014-02-28T21:39:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jens Lehmann <Jens.Lehmann@web.de> writes:\n\n> Good point. What about this?\n>\n>\n>  Documentation/git-submodule.txt | 13 +++++++++++--\n>  git-submodule.sh                |  2 +-\n>  2 files changed, 12 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index bfef8a0..9054217 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -15,8 +15,8 @@ SYNOPSIS\n>  'git submodule' [--quiet] init [--] [<path>...]\n>  'git submodule' [--quiet] deinit [-f|--force] [--] <path>...\n>  'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]\n> -\t      [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]\n> -\t      [--merge] [--recursive] [--] [<path>...]\n> +\t      [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>]\n> +\t      [--depth <depth>] [--recursive] [--] [<path>...]\n\nThis has already been done by 23d25e48 (submodule: explicit local\nbranch creation in module_clone, 2014-01-26).  That commit also adds\nsome text to the description of 'update' subcommand, but not a\nseparate entry for '--checkout' mode.\n\nDoes the result of applying this patch except for this particular\nhunk still make sense as a whole?  It appears to me that it does,\nbut just to double check...\n\nThanks.\n\n>  'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]\n>  \t      [commit] [--] [<path>...]\n>  'git submodule' [--quiet] foreach [--recursive] <command>\n> @@ -287,6 +287,15 @@ SHA-1.  If you don't want to fetch, you should use `submodule update\n>  \tThis option is only valid for the update command.\n>  \tDon't fetch new objects from the remote site.\n>\n> +--checkout::\n> +\tThis option is only valid for the update command.\n> +\tCheckout the commit recorded in the superproject on a detached HEAD\n> +\tin the submodule. This is the default behavior, the main use of\n> +\tthis option is to override `submodule.$name.update` when set to\n> +\t`merge`, `rebase` or `none`.\n> +\tIf the key `submodule.$name.update` is either not explicitly set or\n> +\tset to `checkout`, this option is implicit.\n> +\n>  --merge::\n>  \tThis option is only valid for the update command.\n>  \tMerge the commit recorded in the superproject into the current branch\n> diff --git a/git-submodule.sh b/git-submodule.sh\n> index 4a30087..65cf963 100755\n> --- a/git-submodule.sh\n> +++ b/git-submodule.sh\n> @@ -9,7 +9,7 @@ USAGE=\"[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <re\n>     or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...]\n>     or: $dashless [--quiet] init [--] [<path>...]\n>     or: $dashless [--quiet] deinit [-f|--force] [--] <path>...\n> -   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...]\n> +   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] [--recursive] [--] [<path>...]\n>     or: $dashless [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]\n>     or: $dashless [--quiet] foreach [--recursive] <command>\n>     or: $dashless [--quiet] sync [--recursive] [--] [<path>...]\"\n"},{"id":"235675","messageId":"53111087.1000909@web.de","threadId":"35951","inReplyTo":"xmqqbnxqudbf.fsf@gitster.dls.corp.google.com","subject":"[PATCH v2] submodule update: consistently document the '--checkout' option","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2014-02-28T22:41:11Z","receivedAt":"2014-02-28T22:41:11Z","isPatch":true,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Commit 322bb6e12f (add update 'none' flag to disable update of submodule\nby default) added the '--checkout' option to \"git submodule update\" but\nforgot to explicitly document it in synopsis, usage string and man page\n(It is only mentioned implicitly in the man page). In 23d25e48 (submodule:\nexplicit local branch creation in module_clone) the synopsis of the man\npage was updated, but the \"OPTIONS\" section of the man page and the usage\nstring of the git-submodule script still do not mention the '--checkout'\noption.\n\nFix that by documenting this option in usage string and the \"OPTIONS\"\nsection of man page too. While at it group the update-mode options into\na single set in the usage string.\n\nReported-by: Matthijs Kooijman <matthijs@stdin.nl>\nSigned-off-by: Jens Lehmann <Jens.Lehmann@web.de>\n---\n\nAm 28.02.2014 21:39, schrieb Junio C Hamano:\n> Jens Lehmann <Jens.Lehmann@web.de> writes:\n> \n>> Good point. What about this?\n>>\n>>\n>>  Documentation/git-submodule.txt | 13 +++++++++++--\n>>  git-submodule.sh                |  2 +-\n>>  2 files changed, 12 insertions(+), 3 deletions(-)\n>>\n>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n>> index bfef8a0..9054217 100644\n>> --- a/Documentation/git-submodule.txt\n>> +++ b/Documentation/git-submodule.txt\n>> @@ -15,8 +15,8 @@ SYNOPSIS\n>>  'git submodule' [--quiet] init [--] [<path>...]\n>>  'git submodule' [--quiet] deinit [-f|--force] [--] <path>...\n>>  'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]\n>> -\t      [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]\n>> -\t      [--merge] [--recursive] [--] [<path>...]\n>> +\t      [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>]\n>> +\t      [--depth <depth>] [--recursive] [--] [<path>...]\n> \n> This has already been done by 23d25e48 (submodule: explicit local\n> branch creation in module_clone, 2014-01-26).  That commit also adds\n> some text to the description of 'update' subcommand, but not a\n> separate entry for '--checkout' mode.\n\nThanks, I missed that one.\n\n> Does the result of applying this patch except for this particular\n> hunk still make sense as a whole?  It appears to me that it does,\n> but just to double check...\n\nYes, it still makes sense. But I updated the commit message to\nalso mention 23d25e48.\n\n\n Documentation/git-submodule.txt | 9 +++++++++\n git-submodule.sh                | 2 +-\n 2 files changed, 10 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 21cb59a..dab817d 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -315,6 +315,15 @@ the submodule itself.\n \tThis option is only valid for the update command.\n \tDon't fetch new objects from the remote site.\n\n+--checkout::\n+\tThis option is only valid for the update command.\n+\tCheckout the commit recorded in the superproject on a detached HEAD\n+\tin the submodule. This is the default behavior, the main use of\n+\tthis option is to override `submodule.$name.update` when set to\n+\t`merge`, `rebase` or `none`.\n+\tIf the key `submodule.$name.update` is either not explicitly set or\n+\tset to `checkout`, this option is implicit.\n+\n --merge::\n \tThis option is only valid for the update command.\n \tMerge the commit recorded in the superproject into the current branch\ndiff --git a/git-submodule.sh b/git-submodule.sh\nindex a33f68d..6135cfa 100755\n--- a/git-submodule.sh\n+++ b/git-submodule.sh\n@@ -9,7 +9,7 @@ USAGE=\"[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <re\n    or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...]\n    or: $dashless [--quiet] init [--] [<path>...]\n    or: $dashless [--quiet] deinit [-f|--force] [--] <path>...\n-   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...]\n+   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] [--recursive] [--] [<path>...]\n    or: $dashless [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]\n    or: $dashless [--quiet] foreach [--recursive] <command>\n    or: $dashless [--quiet] sync [--recursive] [--] [<path>...]\"\n-- \n1.8.3.1\n"}]}