{"thread":{"id":"27897","subject":"[PATCH] Documentation/submodule: add command references and update options","startedAt":"2011-07-23T19:00:36Z","lastAt":"2011-07-26T18:54:03Z","messageCount":4,"participants":["Jens Lehmann","Junio C Hamano","Marc Branchaud"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"171897","messageId":"4E2B1A54.2000605@web.de","threadId":"27897","inReplyTo":null,"subject":"[PATCH] Documentation/submodule: add command references and update options","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2011-07-23T19:00:36Z","receivedAt":"2011-07-23T19:00:36Z","isPatch":true,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Reference the \"git diff\" and \"git status\" commands where they learned\nfunctionality that in earlier git versions was only available through the\n'summary' and 'status' subcommands of \"git submodule\".\n\nThe short option '-n' for '--summary-limit' was missing from the synopsis\nand the --init option was missing from the \"options\" section, add those\nthere. And while at it, quote all options so they are decorated properly\nin the output formats which support that.\n\nSigned-off-by: Jens Lehmann <Jens.Lehmann@web.de>\n---\n\nThis patch addresses some issues with the current documentation which were\nbrought up on the list.\n\n Documentation/git-submodule.txt |   30 ++++++++++++++++++++++--------\n 1 files changed, 22 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 0ec8574..e749aa5 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -15,7 +15,8 @@ SYNOPSIS\n 'git submodule' [--quiet] init [--] [<path>...]\n 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase]\n \t      [--reference <repository>] [--merge] [--recursive] [--] [<path>...]\n-'git submodule' [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]\n+'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]\n+\t      [commit] [--] [<path>...]\n 'git submodule' [--quiet] foreach [--recursive] <command>\n 'git submodule' [--quiet] sync [--] [<path>...]\n\n@@ -110,6 +111,11 @@ status::\n +\n If '--recursive' is specified, this command will recurse into nested\n submodules, and show their status as well.\n++\n+If you are only interested in changes of the currently initialized\n+submodules with respect to the commit recorded in the index or the HEAD,\n+linkgit:git-status[1] and linkgit:git-diff[1] will provide that information\n+too (and can also report changes to a submodule's work tree).\n\n init::\n \tInitialize the submodules, i.e. register each submodule name\n@@ -131,7 +137,7 @@ update::\n +\n If the submodule is not yet initialized, and you just want to use the\n setting as stored in .gitmodules, you can automatically initialize the\n-submodule with the --init option.\n+submodule with the '--init' option.\n +\n If '--recursive' is specified, this command will recurse into the\n registered submodules, and update any nested submodules within.\n@@ -140,11 +146,14 @@ summary::\n \tShow commit summary between the given commit (defaults to HEAD) and\n \tworking tree/index. For a submodule in question, a series of commits\n \tin the submodule between the given super project commit and the\n-\tindex or working tree (switched by --cached) are shown. If the option\n-\t--files is given, show the series of commits in the submodule between\n+\tindex or working tree (switched by '--cached') are shown. If the option\n+\t'--files' is given, show the series of commits in the submodule between\n \tthe index of the super project and the working tree of the submodule\n-\t(this option doesn't allow to use the --cached option or to provide an\n+\t(this option doesn't allow to use the '--cached' option or to provide an\n \texplicit commit).\n++\n+Using the '--submodule=log' option with linkgit:git-diff[1] will provide the\n+same information.\n\n foreach::\n \tEvaluates an arbitrary shell command in each checked out submodule.\n@@ -155,9 +164,9 @@ foreach::\n \tsuperproject, $sha1 is the commit as recorded in the superproject,\n \tand $toplevel is the absolute path to the top-level of the superproject.\n \tAny submodules defined in the superproject but not checked out are\n-\tignored by this command. Unless given --quiet, foreach prints the name\n+\tignored by this command. Unless given '--quiet', foreach prints the name\n \tof each submodule before evaluating the command.\n-\tIf --recursive is given, submodules are traversed recursively (i.e.\n+\tIf '--recursive' is given, submodules are traversed recursively (i.e.\n \tthe given shell command is evaluated in nested submodules as well).\n \tA non-zero return from the command in any submodule causes\n \tthe processing to terminate. This can be overridden by adding '|| :'\n@@ -237,13 +246,18 @@ OPTIONS\n \tIf the key `submodule.$name.update` is set to `rebase`, this option is\n \timplicit.\n\n+--init::\n+\tThis option is only valid for the update command.\n+\tInitialize all submodules for which \"git submodule init\" has not been\n+\tcalled so far before updating.\n+\n --reference <repository>::\n \tThis option is only valid for add and update commands.  These\n \tcommands sometimes need to clone a remote repository. In this case,\n \tthis option will be passed to the linkgit:git-clone[1] command.\n +\n *NOTE*: Do *not* use this option unless you have read the note\n-for linkgit:git-clone[1]'s --reference and --shared options carefully.\n+for linkgit:git-clone[1]'s '--reference' and '--shared' options carefully.\n\n --recursive::\n \tThis option is only valid for foreach, update and status commands.\n-- \n1.7.6.356.g65c4e\n"},{"id":"172008","messageId":"7vmxg2qf0j.fsf@alter.siamese.dyndns.org","threadId":"27897","inReplyTo":"4E2B1A54.2000605@web.de","subject":"Re: [PATCH] Documentation/submodule: add command references and update options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-07-25T20:30:52Z","receivedAt":"2011-07-25T20:30:52Z","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> @@ -131,7 +137,7 @@ update::\n>  +\n>  If the submodule is not yet initialized, and you just want to use the\n>  setting as stored in .gitmodules, you can automatically initialize the\n> -submodule with the --init option.\n> +submodule with the '--init' option.\n\nDon't we want to use\n\n\tthe `--init` option\n\ninstead for consistency? After all, that is what the users actually type.\n\n\t$ git grep -e \"\\`--[a-z]\" Documentation/ | wc -l\n        287\n        $ git grep -e \"'--[a-z]\" Documentation/ | wc -l\n        132\n\n> @@ -140,11 +146,14 @@ summary::\n>  \tShow commit summary between the given commit (defaults to HEAD) and\n>  \tworking tree/index. For a submodule in question, a series of commits\n>  \tin the submodule between the given super project commit and the\n> -\tindex or working tree (switched by --cached) are shown. If the option\n> -\t--files is given, show the series of commits in the submodule between\n> +\tindex or working tree (switched by '--cached') are shown. If the option\n> +\t'--files' is given, show the series of commits in the submodule between\n>  \tthe index of the super project and the working tree of the submodule\n> -\t(this option doesn't allow to use the --cached option or to provide an\n> +\t(this option doesn't allow to use the '--cached' option or to provide an\n>  \texplicit commit).\n> ++\n> +Using the '--submodule=log' option with linkgit:git-diff[1] will provide the\n> +same information.\n\nI am not a huge fan of these extra paragraphs, especially in reality it is\nnot \"provide the same\" but \"the same and a lot of other\".\n\nI dunno.\n"},{"id":"172088","messageId":"4E2F0AF7.2070306@web.de","threadId":"27897","inReplyTo":"7vmxg2qf0j.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/submodule: add command references and update options","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2011-07-26T18:44:07Z","receivedAt":"2011-07-26T18:44:07Z","isPatch":true,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Am 25.07.2011 22:30, schrieb Junio C Hamano:\n> Jens Lehmann <Jens.Lehmann@web.de> writes:\n> \n>> @@ -131,7 +137,7 @@ update::\n>>  +\n>>  If the submodule is not yet initialized, and you just want to use the\n>>  setting as stored in .gitmodules, you can automatically initialize the\n>> -submodule with the --init option.\n>> +submodule with the '--init' option.\n> \n> Don't we want to use\n> \n> \tthe `--init` option\n> \n> instead for consistency? After all, that is what the users actually type.\n> \n> \t$ git grep -e \"\\`--[a-z]\" Documentation/ | wc -l\n>         287\n>         $ git grep -e \"'--[a-z]\" Documentation/ | wc -l\n>         132\n\nFine by me, I just followed the style I found there. Will change all\noption names (including those who are using '--init' right now) to\n`--init` in the next iteration.\n\n>> @@ -140,11 +146,14 @@ summary::\n>>  \tShow commit summary between the given commit (defaults to HEAD) and\n>>  \tworking tree/index. For a submodule in question, a series of commits\n>>  \tin the submodule between the given super project commit and the\n>> -\tindex or working tree (switched by --cached) are shown. If the option\n>> -\t--files is given, show the series of commits in the submodule between\n>> +\tindex or working tree (switched by '--cached') are shown. If the option\n>> +\t'--files' is given, show the series of commits in the submodule between\n>>  \tthe index of the super project and the working tree of the submodule\n>> -\t(this option doesn't allow to use the --cached option or to provide an\n>> +\t(this option doesn't allow to use the '--cached' option or to provide an\n>>  \texplicit commit).\n>> ++\n>> +Using the '--submodule=log' option with linkgit:git-diff[1] will provide the\n>> +same information.\n> \n> I am not a huge fan of these extra paragraphs, especially in reality it is\n> not \"provide the same\" but \"the same and a lot of other\".\n>\n> I dunno.\n\nI added them because in a discussion with Marc it became apparent that users\ncan't learn about what diff and status can do for them by checking the submodule\nman-page. But you are right about \"the same and a lot of other\", I will update\nthe wording of those paragraphs.\n\nMaybe someone else has a better idea how to inform users that git diff and\nstatus can tell you a lot (and sometimes even more than the submodule script)\nabout the state submodules are in?\n"},{"id":"172090","messageId":"4E2F0D4B.2000209@xiplink.com","threadId":"27897","inReplyTo":"4E2F0AF7.2070306@web.de","subject":"Re: [PATCH] Documentation/submodule: add command references and update options","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2011-07-26T18:54:03Z","receivedAt":"2011-07-26T18:54:03Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 11-07-26 02:44 PM, Jens Lehmann wrote:\n> Am 25.07.2011 22:30, schrieb Junio C Hamano:\n>> Jens Lehmann <Jens.Lehmann@web.de> writes:\n>>\n>>> @@ -140,11 +146,14 @@ summary::\n>>>  \tShow commit summary between the given commit (defaults to HEAD) and\n>>>  \tworking tree/index. For a submodule in question, a series of commits\n>>>  \tin the submodule between the given super project commit and the\n>>> -\tindex or working tree (switched by --cached) are shown. If the option\n>>> -\t--files is given, show the series of commits in the submodule between\n>>> +\tindex or working tree (switched by '--cached') are shown. If the option\n>>> +\t'--files' is given, show the series of commits in the submodule between\n>>>  \tthe index of the super project and the working tree of the submodule\n>>> -\t(this option doesn't allow to use the --cached option or to provide an\n>>> +\t(this option doesn't allow to use the '--cached' option or to provide an\n>>>  \texplicit commit).\n>>> ++\n>>> +Using the '--submodule=log' option with linkgit:git-diff[1] will provide the\n>>> +same information.\n>>\n>> I am not a huge fan of these extra paragraphs, especially in reality it is\n>> not \"provide the same\" but \"the same and a lot of other\".\n>>\n>> I dunno.\n> \n> I added them because in a discussion with Marc it became apparent that users\n> can't learn about what diff and status can do for them by checking the submodule\n> man-page. But you are right about \"the same and a lot of other\", I will update\n> the wording of those paragraphs.\n> \n> Maybe someone else has a better idea how to inform users that git diff and\n> status can tell you a lot (and sometimes even more than the submodule script)\n> about the state submodules are in?\n\nI thought the brief sentence in the patch was fine, myself.\n\n\t\tM.\n"}]}