{"thread":{"id":"27988","subject":"[PATCH v2] Documentation/submodule: add command references and update options","startedAt":"2011-08-01T20:49:21Z","lastAt":"2011-08-01T22:34:48Z","messageCount":2,"participants":["Jens Lehmann","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"172599","messageId":"4E371151.4040407@web.de","threadId":"27988","inReplyTo":null,"subject":"[PATCH v2] Documentation/submodule: add command references and update options","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2011-08-01T20:49:21Z","receivedAt":"2011-08-01T20:49:21Z","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 in backticks so they are\ndecorated properly in the output formats which support that.\n\nSigned-off-by: Jens Lehmann <Jens.Lehmann@web.de>\n---\n\nIn this version the options are quoted in backticks and the phrase \"will\nprovide the same information\" has been changed to \"provide that information\ntoo\" to inform the user that it will provide \"the same and a lot of other\"\ninformation.\n\n\n Documentation/git-submodule.txt |   38 ++++++++++++++++++++++++++------------\n 1 files changed, 26 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 0ec8574..67cf5f0 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@@ -108,8 +109,13 @@ status::\n \trepository and `U` if the submodule has merge conflicts.\n \tThis command is the default command for 'git submodule'.\n +\n-If '--recursive' is specified, this command will recurse into nested\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@@ -125,26 +131,29 @@ init::\n update::\n \tUpdate the registered submodules, i.e. clone missing submodules and\n \tcheckout the commit specified in the index of the containing repository.\n-\tThis will make the submodules HEAD be detached unless '--rebase' or\n-\t'--merge' is specified or the key `submodule.$name.update` is set to\n+\tThis will make the submodules HEAD be detached unless `--rebase` or\n+\t`--merge` is specified or the key `submodule.$name.update` is set to\n \t`rebase` or `merge`.\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+If `--recursive` is specified, this command will recurse into the\n registered submodules, and update any nested submodules within.\n\n 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 that\n+information too.\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.351.gb35ac\n"},{"id":"172612","messageId":"7vr554hibb.fsf@alter.siamese.dyndns.org","threadId":"27988","inReplyTo":"4E371151.4040407@web.de","subject":"Re: [PATCH v2] Documentation/submodule: add command references and update options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-08-01T22:34:48Z","receivedAt":"2011-08-01T22:34:48Z","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> Reference the \"git diff\" and \"git status\" commands where they learned\n> functionality that in earlier git versions was only available through the\n> 'summary' and 'status' subcommands of \"git submodule\".\n\nThanks; will queue.\n"}]}