{"thread":{"id":"42987","subject":"[PATCH 2/2] submodule update documentation: don't repeat ourselves","startedAt":"2016-08-02T18:25:33Z","lastAt":"2016-08-02T22:25:41Z","messageCount":5,"participants":["Stefan Beller","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"292854","messageId":"20160802182152.20637-2-sbeller@google.com","threadId":"42987","inReplyTo":"20160802182152.20637-1-sbeller@google.com","subject":"[PATCH 2/2] submodule update documentation: don't repeat ourselves","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-08-02T18:21:52Z","receivedAt":"2016-08-02T18:25:33Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"The documentation for the `git submodule update` command, repeats itself\nfor each update option, \"This is done when <option> is given, or no\noption is given and `submodule.<name>.update` is set to <string>.\n\nAvoid these repetitive clauses by stating the command line options take\nprecedence over configured options.\n\nAlso add 'none' to the list of options instead of mentioning it in the\nfollowing running text and split the list into two parts, one that is\naccessible via the command line and one that is only reachable via the\nconfiguration variables.\n\nSigned-off-by: Stefan Beller <sbeller@google.com>\n---\n Documentation/git-submodule.txt | 30 ++++++++++++++----------------\n 1 file changed, 14 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 1452c31..9b5abaf 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -158,13 +158,13 @@ Update the registered submodules to match what the superproject\n expects by cloning missing submodules and updating the working tree of\n the submodules. The \"updating\" can be done in several ways depending\n on command line options and the value of `submodule.<name>.update`\n-configuration variable. Supported update procedures are:\n+configuration variable. The command line option takes precedence over\n+the configuration variable. if neither is given, a checkout is performed.\n+update procedures supported both from the command line as well as setting\n+`submodule.<name>.update`:\n \n \tcheckout;; the commit recorded in the superproject will be\n-\t    checked out in the submodule on a detached HEAD. This is\n-\t    done when `--checkout` option is given, or no option is\n-\t    given, and `submodule.<name>.update` is unset, or if it is\n-\t    set to 'checkout'.\n+\t    checked out in the submodule on a detached HEAD.\n +\n If `--force` is specified, the submodule will be checked out (using\n `git checkout --force` if appropriate), even if the commit specified\n@@ -172,23 +172,21 @@ in the index of the containing repository already matches the commit\n checked out in the submodule.\n \n \trebase;; the current branch of the submodule will be rebased\n-\t    onto the commit recorded in the superproject. This is done\n-\t    when `--rebase` option is given, or no option is given, and\n-\t    `submodule.<name>.update` is set to 'rebase'.\n+\t    onto the commit recorded in the superproject.\n \n \tmerge;; the commit recorded in the superproject will be merged\n-\t    into the current branch in the submodule. This is done\n-\t    when `--merge` option is given, or no option is given, and\n-\t    `submodule.<name>.update` is set to 'merge'.\n+\t    into the current branch in the submodule.\n+\n+The following procedures are only available via the `submodule.<name>.update`\n+configuration variable:\n \n \tcustom command;; arbitrary shell command that takes a single\n \t    argument (the sha1 of the commit recorded in the\n-\t    superproject) is executed. This is done when no option is\n-\t    given, and `submodule.<name>.update` has the form of\n-\t    '!command'.\n+\t    superproject) is executed. When `submodule.<name>.update`\n+\t    is set to '!command', the remainder after the exclamation mark\n+\t    is the custom command.\n \n-When no option is given and `submodule.<name>.update` is set to 'none',\n-the submodule is not updated.\n+\tnone;; the submodule is not updated.\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-- \n2.9.2.525.g1760797\n\n"},{"id":"292855","messageId":"20160802182152.20637-1-sbeller@google.com","threadId":"42987","inReplyTo":null,"subject":"[PATCH 1/2] submodule documentation: add options to the subcommand","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-08-02T18:21:51Z","receivedAt":"2016-08-02T18:25:36Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"When reading up on a subcommand of `gi submodule`, it is convenient\nto have its options nearby and not just at the top of the man page.\nAdd the options to each subcommand.\n\nWhile at it, also document the `--checkout` option for `update`.\n\nSigned-off-by: Stefan Beller <sbeller@google.com>\n---\n\n  This mini series applies to master, there no other patches in flight\n  that touch Documentation/git-submodules.txt except\n  sb/submodule-default-paths, which we are holding back currently.\n  \n  Thanks,\n  Stefan\n\n Documentation/git-submodule.txt | 18 +++++++++---------\n 1 file changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex bf3bb37..1452c31 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -15,7 +15,7 @@ SYNOPSIS\n 'git submodule' [--quiet] init [--] [<path>...]\n 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)\n 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]\n-\t      [--[no-]recommend-shallow] [-f|--force] [--rebase|--merge]\n+\t      [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge]\n \t      [--reference <repository>] [--depth <depth>] [--recursive]\n \t      [--jobs <n>] [--] [<path>...]\n 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]\n@@ -62,7 +62,7 @@ if you choose to go that route.\n \n COMMANDS\n --------\n-add::\n+add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]::\n \tAdd the given repository as a submodule at the given path\n \tto the changeset to be committed next to the current\n \tproject: the current project is termed the \"superproject\".\n@@ -103,7 +103,7 @@ together in the same relative location, and only the\n superproject's URL needs to be provided: git-submodule will correctly\n locate the submodule using the relative URL in .gitmodules.\n \n-status::\n+status [--cached] [--recursive] [--] [<path>...]::\n \tShow the status of the submodules. This will print the SHA-1 of the\n \tcurrently checked out commit for each submodule, along with the\n \tsubmodule path and the output of 'git describe' for the\n@@ -120,7 +120,7 @@ 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+init [--] [<path>...]::\n \tInitialize the submodules recorded in the index (which were\n \tadded and committed elsewhere) by copying submodule\n \tnames and urls from .gitmodules to .git/config.\n@@ -135,7 +135,7 @@ init::\n \tthe explicit 'init' step if you do not intend to customize\n \tany submodule locations.\n \n-deinit::\n+deinit [-f|--force] (--all|[--] <path>...)::\n \tUnregister the given submodules, i.e. remove the whole\n \t`submodule.$name` section from .git/config together with their work\n \ttree. Further calls to `git submodule update`, `git submodule foreach`\n@@ -151,7 +151,7 @@ instead of deinit-ing everything, to prevent mistakes.\n If `--force` is specified, the submodule's working tree will\n be removed even if it contains local modifications.\n \n-update::\n+update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]::\n +\n --\n Update the registered submodules to match what the superproject\n@@ -197,7 +197,7 @@ submodule with the `--init` option.\n If `--recursive` is specified, this command will recurse into the\n registered submodules, and update any nested submodules within.\n --\n-summary::\n+summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::\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@@ -210,7 +210,7 @@ summary::\n Using the `--submodule=log` option with linkgit:git-diff[1] will provide that\n information too.\n \n-foreach::\n+foreach [--recursive] <command>::\n \tEvaluates an arbitrary shell command in each checked out submodule.\n \tThe command has access to the variables $name, $path, $sha1 and\n \t$toplevel:\n@@ -231,7 +231,7 @@ As an example, +git submodule foreach \\'echo $path {backtick}git\n rev-parse HEAD{backtick}'+ will show the path and currently checked out\n commit for each submodule.\n \n-sync::\n+sync [--recursive] [--] [<path>...]::\n \tSynchronizes submodules' remote URL configuration setting\n \tto the value specified in .gitmodules. It will only affect those\n \tsubmodules which already have a URL entry in .git/config (that is the\n-- \n2.9.2.525.g1760797\n\n"},{"id":"292870","messageId":"xmqqtwf2c0aw.fsf@gitster.mtv.corp.google.com","threadId":"42987","inReplyTo":"20160802182152.20637-1-sbeller@google.com","subject":"Re: [PATCH 1/2] submodule documentation: add options to the subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-02T21:45:27Z","receivedAt":"2016-08-02T21:51:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller <sbeller@google.com> writes:\n\n> When reading up on a subcommand of `gi submodule`, it is convenient\n\ns/gi /git /;\n\n> to have its options nearby and not just at the top of the man page.\n> Add the options to each subcommand.\n>\n> While at it, also document the `--checkout` option for `update`.\n\nI do find the resulting per-subcommand description easier to read\nwith this change.\n\nPerhaps we want to go one step further and change the SYNOPSIS so\nthat per-subcommand options are not described there at all?\nI.e.e.g.\n\n-    'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]...\n+    'git submodule' [--quiet] update [<option>...]\n\n\n> @@ -231,7 +231,7 @@ As an example, +git submodule foreach \\'echo $path {backtick}git\n>  rev-parse HEAD{backtick}'+ will show the path and currently checked out\n>  commit for each submodule.\n>  \n> -sync::\n> +sync [--recursive] [--] [<path>...]::\n>  \tSynchronizes submodules' remote URL configuration setting\n>  \tto the value specified in .gitmodules. It will only affect those\n>  \tsubmodules which already have a URL entry in .git/config (that is the\n"},{"id":"292871","messageId":"CAGZ79kYChcixXtOc2HigHCY7S5bteO1QZau+4cqQYbxtHW3wDA@mail.gmail.com","threadId":"42987","inReplyTo":"xmqqtwf2c0aw.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 1/2] submodule documentation: add options to the subcommand","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-08-02T22:02:00Z","receivedAt":"2016-08-02T22:09:23Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Tue, Aug 2, 2016 at 2:45 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> Stefan Beller <sbeller@google.com> writes:\n>\n>> When reading up on a subcommand of `gi submodule`, it is convenient\n>\n> s/gi /git /;\n\nwill fix.\n\nAnd in the neighboring thread you just pointed out you used to just correct\nspelling fixes like this. I think it really depends on the workflow of the\ncontributor. As I do the interdiff of the next version of the series against\nyour tree I'll be likely to notice such typos in the content, but not in\ncommit messages.\n\n>\n>> to have its options nearby and not just at the top of the man page.\n>> Add the options to each subcommand.\n>>\n>> While at it, also document the `--checkout` option for `update`.\n>\n> I do find the resulting per-subcommand description easier to read\n> with this change.\n>\n> Perhaps we want to go one step further and change the SYNOPSIS so\n> that per-subcommand options are not described there at all?\n> I.e.e.g.\n>\n> -    'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]...\n> +    'git submodule' [--quiet] update [<option>...]\n\nwill do.\n\nMy original intention was to get rid of the duplicates in the OPTIONS\nsection, where each option has\n\n    This option is only valid for <subcommand> and <subcommand>\n\nin its description. So I looked at the `stash` man page, which has\nthe options listed with the subcommands (and also has [<options>]\nin the SYNOPSIS but also some of the options as well).\n\nI think only the long option lists (i.e. those that are more than one line)\nwill be collapsed. The short options are ok, specifically when you just\nwant to know e.g. if foreach supports the recursive option. Then you\ncan open the man page and have no need to scroll down to the foreach\ncommand.\n\nThanks,\nStefan\n"},{"id":"292873","messageId":"xmqqh9b2byg2.fsf@gitster.mtv.corp.google.com","threadId":"42987","inReplyTo":"CAGZ79kYChcixXtOc2HigHCY7S5bteO1QZau+4cqQYbxtHW3wDA@mail.gmail.com","subject":"Re: [PATCH 1/2] submodule documentation: add options to the subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-02T22:25:33Z","receivedAt":"2016-08-02T22:25:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller <sbeller@google.com> writes:\n\n> On Tue, Aug 2, 2016 at 2:45 PM, Junio C Hamano <gitster@pobox.com> wrote:\n>> Stefan Beller <sbeller@google.com> writes:\n>>\n>>> When reading up on a subcommand of `gi submodule`, it is convenient\n>>\n>> s/gi /git /;\n>\n> will fix.\n>\n> And in the neighboring thread you just pointed out you used to just correct\n> spelling fixes like this. I think it really depends on the workflow of the\n> contributor. As I do the interdiff of the next version of the series against\n> your tree I'll be likely to notice such typos in the content, but not in\n> commit messages.\n\n\"git tbdiff\" is your friend ;-)\n"}]}