git submodule manpage does not document --checkout
Hi,
it seems git submodule supports --checkout, which is also mentioned indirectly in the manpage. However, the option itself is not mentioned in the synopsis or detailed option list.
Gr.
Matthijs
PATCH 1/1 submodule update: document the '--checkout' option
Commit 322bb6e12f (add update 'none' flag to disable update of submodule by default) added the '--checkout' option to "git submodule update" but forgot to explicitly document it in the synopsis and the man page (It is only mentioned implicitly in the man page).
Document this option in synopsis and man page too. While at it make it more clear that only one of '--checkout', '--merge' or '--rebase' make sense by grouping them together.
---
Am 25.02.2014 11:03, schrieb Matthijs Kooijman:
Quoted 3 lines
it seems git submodule supports --checkout, which is also mentioned indirectly in the manpage. However, the option itself is not mentioned in the synopsis or detailed option list.
Good point. What about this?
Documentation/git-submodule.txt | 13 +++++++++++-- git-submodule.sh | 2 +- 2 files changed, 12 insertions(+), 3 deletions(-)
Documentation/git-submodule.txt +11 -2
@@ -15,8 +15,8 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] [--] <path>... 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] - [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>] - [--merge] [--recursive] [--] [<path>...] + [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] + [--depth <depth>] [--recursive] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command>
@@ -287,6 +287,15 @@ SHA-1. If you don't want to fetch, you should use `submodule update This option is only valid for the update command. Don't fetch new objects from the remote site. +--checkout:: + This option is only valid for the update command. + Checkout the commit recorded in the superproject on a detached HEAD + in the submodule. This is the default behavior, the main use of + this option is to override `submodule.$name.update` when set to + `merge`, `rebase` or `none`. + If the key `submodule.$name.update` is either not explicitly set or + set to `checkout`, this option is implicit. + --merge:: This option is only valid for the update command. Merge the commit recorded in the superproject into the current branch
git-submodule.sh +1 -1
@@ -9,7 +9,7 @@ USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <re or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...] or: $dashless [--quiet] init [--] [<path>...] or: $dashless [--quiet] deinit [-f|--force] [--] <path>... - or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<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> or: $dashless [--quiet] sync [--recursive] [--] [<path>...]"
Signature · 1 line
1.8.3.1
Re: [PATCH] submodule update: document the '--checkout' option
Quoted 12 lines · Jens Lehmann
Good point. What about this?
Documentation/git-submodule.txt | 13 +++++++++++-- git-submodule.sh | 2 +- 2 files changed, 12 insertions(+), 3 deletions(-)Documentation/git-submodule.txt +0
-0
Documentation/git-submodule.txt SYNOPSIS · line 19
Quoted 7 lines
Documentation/git-submodule.txt +2
-2@@ -15,8 +15,8 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] [--] <path>... 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] - [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>] - [--merge] [--recursive] [--] [<path>...] + [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] + [--depth <depth>] [--recursive] [--] [<path>...]
This has already been done by 23d25e48 (submodule: explicit local branch creation in module_clone, 2014-01-26). That commit also adds some text to the description of 'update' subcommand, but not a separate entry for '--checkout' mode.
Does the result of applying this patch except for this particular hunk still make sense as a whole? It appears to me that it does, but just to double check...
Thanks.
Quoted 32 lines
Documentation/git-submodule.txt +9
-0'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command>@@ -287,6 +287,15 @@ SHA-1. If you don't want to fetch, you should use `submodule update This option is only valid for the update command. Don't fetch new objects from the remote site. +--checkout:: + This option is only valid for the update command. + Checkout the commit recorded in the superproject on a detached HEAD + in the submodule. This is the default behavior, the main use of + this option is to override `submodule.$name.update` when set to + `merge`, `rebase` or `none`. + If the key `submodule.$name.update` is either not explicitly set or + set to `checkout`, this option is implicit. + --merge:: This option is only valid for the update command. Merge the commit recorded in the superproject into the current branchgit-submodule.sh +1
-1@@ -9,7 +9,7 @@ USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <re or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...] or: $dashless [--quiet] init [--] [<path>...] or: $dashless [--quiet] deinit [-f|--force] [--] <path>... - or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<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> or: $dashless [--quiet] sync [--recursive] [--] [<path>...]"
PATCH v2 1/1 submodule update: consistently document the '--checkout' option
Commit 322bb6e12f (add update 'none' flag to disable update of submodule by default) added the '--checkout' option to "git submodule update" but forgot to explicitly document it in synopsis, usage string and man page (It is only mentioned implicitly in the man page). In 23d25e48 (submodule:
explicit local branch creation in module_clone) the synopsis of the man page was updated, but the "OPTIONS" section of the man page and the usage string of the git-submodule script still do not mention the '--checkout' option.
Fix that by documenting this option in usage string and the "OPTIONS" section of man page too. While at it group the update-mode options into a single set in the usage string.
---
Am 28.02.2014 21:39, schrieb Junio C Hamano:
Quoted 18 lines
Quoted 16 lines · Jens Lehmann
Good point. What about this?
Documentation/git-submodule.txt | 13 +++++++++++-- git-submodule.sh | 2 +- 2 files changed, 12 insertions(+), 3 deletions(-)Documentation/git-submodule.txt +0
-1@@ -15,8 +15,8 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] [--] <path>... 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] - [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]
Quoted 8 lines
Documentation/git-submodule.txt SYNOPSIS · line 19
Quoted 3 lines
Documentation/git-submodule.txt +2
-1- [--merge] [--recursive] [--] [<path>...] + [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] + [--depth <depth>] [--recursive] [--] [<path>...]This has already been done by
23d25e48(submodule: explicit local branch creation inmodule_clone, 2014-01-26). That commit also adds some text to the description of 'update' subcommand, but not a separate entry for '--checkout' mode.
Thanks, I missed that one.
Quoted 3 lines
Does the result of applying this patch except for this particular hunk still make sense as a whole? It appears to me that it does, but just to double check...
Yes, it still makes sense. But I updated the commit message to also mention 23d25e48.
Documentation/git-submodule.txt | 9 +++++++++ git-submodule.sh | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-)
Documentation/git-submodule.txt +9 -0
@@ -315,6 +315,15 @@ the submodule itself. This option is only valid for the update command. Don't fetch new objects from the remote site. +--checkout:: + This option is only valid for the update command. + Checkout the commit recorded in the superproject on a detached HEAD + in the submodule. This is the default behavior, the main use of + this option is to override `submodule.$name.update` when set to + `merge`, `rebase` or `none`. + If the key `submodule.$name.update` is either not explicitly set or + set to `checkout`, this option is implicit. + --merge:: This option is only valid for the update command. Merge the commit recorded in the superproject into the current branch
git-submodule.sh +1 -1
@@ -9,7 +9,7 @@ USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <re or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...] or: $dashless [--quiet] init [--] [<path>...] or: $dashless [--quiet] deinit [-f|--force] [--] <path>... - or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<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> or: $dashless [--quiet] sync [--recursive] [--] [<path>...]"
Signature · 1 line
1.8.3.1