[PATCH 1/2] submodule documentation: add options to the subcommand

[PATCH 1/2] submodule documentation: add options to the subcommand

[Stefan Beller]

When reading up on a subcommand of `gi submodule`, it is convenient
to have its options nearby and not just at the top of the man page.
Add the options to each subcommand.

While at it, also document the `--checkout` option for `update`.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

  This mini series applies to master, there no other patches in flight
  that touch Documentation/git-submodules.txt except
  sb/submodule-default-paths, which we are holding back currently.
  
  Thanks,
  Stefan

 Documentation/git-submodule.txt | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index bf3bb37..1452c31 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -15,7 +15,7 @@ SYNOPSIS
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)
 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
-	      [--[no-]recommend-shallow] [-f|--force] [--rebase|--merge]
+	      [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge]
 	      [--reference <repository>] [--depth <depth>] [--recursive]
 	      [--jobs <n>] [--] [<path>...]
 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
@@ -62,7 +62,7 @@ if you choose to go that route.
 
 COMMANDS
 --------
-add::
+add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]::
 	Add the given repository as a submodule at the given path
 	to the changeset to be committed next to the current
 	project: the current project is termed the "superproject".
@@ -103,7 +103,7 @@ together in the same relative location, and only the
 superproject's URL needs to be provided: git-submodule will correctly
 locate the submodule using the relative URL in .gitmodules.
 
-status::
+status [--cached] [--recursive] [--] [<path>...]::
 	Show the status of the submodules. This will print the SHA-1 of the
 	currently checked out commit for each submodule, along with the
 	submodule path and the output of 'git describe' for the
@@ -120,7 +120,7 @@ submodules with respect to the commit recorded in the index or the HEAD,
 linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
 too (and can also report changes to a submodule's work tree).
 
-init::
+init [--] [<path>...]::
 	Initialize the submodules recorded in the index (which were
 	added and committed elsewhere) by copying submodule
 	names and urls from .gitmodules to .git/config.
@@ -135,7 +135,7 @@ init::
 	the explicit 'init' step if you do not intend to customize
 	any submodule locations.
 
-deinit::
+deinit [-f|--force] (--all|[--] <path>...)::
 	Unregister the given submodules, i.e. remove the whole
 	`submodule.$name` section from .git/config together with their work
 	tree. Further calls to `git submodule update`, `git submodule foreach`
@@ -151,7 +151,7 @@ instead of deinit-ing everything, to prevent mistakes.
 If `--force` is specified, the submodule's working tree will
 be removed even if it contains local modifications.
 
-update::
+update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]::
 +
 --
 Update the registered submodules to match what the superproject
@@ -197,7 +197,7 @@ submodule with the `--init` option.
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
 --
-summary::
+summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::
 	Show commit summary between the given commit (defaults to HEAD) and
 	working tree/index. For a submodule in question, a series of commits
 	in the submodule between the given super project commit and the
@@ -210,7 +210,7 @@ summary::
 Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
 information too.
 
-foreach::
+foreach [--recursive] <command>::
 	Evaluates an arbitrary shell command in each checked out submodule.
 	The command has access to the variables $name, $path, $sha1 and
 	$toplevel:
@@ -231,7 +231,7 @@ As an example, +git submodule foreach \'echo $path {backtick}git
 rev-parse HEAD{backtick}'+ will show the path and currently checked out
 commit for each submodule.
 
-sync::
+sync [--recursive] [--] [<path>...]::
 	Synchronizes submodules' remote URL configuration setting
 	to the value specified in .gitmodules. It will only affect those
 	submodules which already have a URL entry in .git/config (that is the
-- 
2.9.2.525.g1760797

[PATCH 2/2] submodule update documentation: don't repeat ourselves

[Stefan Beller]

The documentation for the `git submodule update` command, repeats itself
for each update option, "This is done when <option> is given, or no
option is given and `submodule.<name>.update` is set to <string>.

Avoid these repetitive clauses by stating the command line options take
precedence over configured options.

Also add 'none' to the list of options instead of mentioning it in the
following running text and split the list into two parts, one that is
accessible via the command line and one that is only reachable via the
configuration variables.

Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/git-submodule.txt | 30 ++++++++++++++----------------
 1 file changed, 14 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 1452c31..9b5abaf 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -158,13 +158,13 @@ Update the registered submodules to match what the superproject
 expects by cloning missing submodules and updating the working tree of
 the submodules. The "updating" can be done in several ways depending
 on command line options and the value of `submodule.<name>.update`
-configuration variable. Supported update procedures are:
+configuration variable. The command line option takes precedence over
+the configuration variable. if neither is given, a checkout is performed.
+update procedures supported both from the command line as well as setting
+`submodule.<name>.update`:
 
 	checkout;; the commit recorded in the superproject will be
-	    checked out in the submodule on a detached HEAD. This is
-	    done when `--checkout` option is given, or no option is
-	    given, and `submodule.<name>.update` is unset, or if it is
-	    set to 'checkout'.
+	    checked out in the submodule on a detached HEAD.
 +
 If `--force` is specified, the submodule will be checked out (using
 `git checkout --force` if appropriate), even if the commit specified
@@ -172,23 +172,21 @@ in the index of the containing repository already matches the commit
 checked out in the submodule.
 
 	rebase;; the current branch of the submodule will be rebased
-	    onto the commit recorded in the superproject. This is done
-	    when `--rebase` option is given, or no option is given, and
-	    `submodule.<name>.update` is set to 'rebase'.
+	    onto the commit recorded in the superproject.
 
 	merge;; the commit recorded in the superproject will be merged
-	    into the current branch in the submodule. This is done
-	    when `--merge` option is given, or no option is given, and
-	    `submodule.<name>.update` is set to 'merge'.
+	    into the current branch in the submodule.
+
+The following procedures are only available via the `submodule.<name>.update`
+configuration variable:
 
 	custom command;; arbitrary shell command that takes a single
 	    argument (the sha1 of the commit recorded in the
-	    superproject) is executed. This is done when no option is
-	    given, and `submodule.<name>.update` has the form of
-	    '!command'.
+	    superproject) is executed. When `submodule.<name>.update`
+	    is set to '!command', the remainder after the exclamation mark
+	    is the custom command.
 
-When no option is given and `submodule.<name>.update` is set to 'none',
-the submodule is not updated.
+	none;; the submodule is not updated.
 
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
-- 
2.9.2.525.g1760797

Re: [PATCH 1/2] submodule documentation: add options to the subcommand

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> When reading up on a subcommand of `gi submodule`, it is convenient

s/gi /git /;

> to have its options nearby and not just at the top of the man page.
> Add the options to each subcommand.
>
> While at it, also document the `--checkout` option for `update`.

I do find the resulting per-subcommand description easier to read
with this change.

Perhaps we want to go one step further and change the SYNOPSIS so
that per-subcommand options are not described there at all?
I.e.e.g.

-    'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]...
+    'git submodule' [--quiet] update [<option>...]


> @@ -231,7 +231,7 @@ As an example, +git submodule foreach \'echo $path {backtick}git
>  rev-parse HEAD{backtick}'+ will show the path and currently checked out
>  commit for each submodule.
>  
> -sync::
> +sync [--recursive] [--] [<path>...]::
>  	Synchronizes submodules' remote URL configuration setting
>  	to the value specified in .gitmodules. It will only affect those
>  	submodules which already have a URL entry in .git/config (that is the

Re: [PATCH 1/2] submodule documentation: add options to the subcommand

[Stefan Beller]

On Tue, Aug 2, 2016 at 2:45 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> When reading up on a subcommand of `gi submodule`, it is convenient
>
> s/gi /git /;

will fix.

And in the neighboring thread you just pointed out you used to just correct
spelling fixes like this. I think it really depends on the workflow of the
contributor. As I do the interdiff of the next version of the series against
your tree I'll be likely to notice such typos in the content, but not in
commit messages.

>
>> to have its options nearby and not just at the top of the man page.
>> Add the options to each subcommand.
>>
>> While at it, also document the `--checkout` option for `update`.
>
> I do find the resulting per-subcommand description easier to read
> with this change.
>
> Perhaps we want to go one step further and change the SYNOPSIS so
> that per-subcommand options are not described there at all?
> I.e.e.g.
>
> -    'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]...
> +    'git submodule' [--quiet] update [<option>...]

will do.

My original intention was to get rid of the duplicates in the OPTIONS
section, where each option has

    This option is only valid for <subcommand> and <subcommand>

in its description. So I looked at the `stash` man page, which has
the options listed with the subcommands (and also has [<options>]
in the SYNOPSIS but also some of the options as well).

I think only the long option lists (i.e. those that are more than one line)
will be collapsed. The short options are ok, specifically when you just
want to know e.g. if foreach supports the recursive option. Then you
can open the man page and have no need to scroll down to the foreach
command.

Thanks,
Stefan

Re: [PATCH 1/2] submodule documentation: add options to the subcommand

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> On Tue, Aug 2, 2016 at 2:45 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Stefan Beller <sbeller@google.com> writes:
>>
>>> When reading up on a subcommand of `gi submodule`, it is convenient
>>
>> s/gi /git /;
>
> will fix.
>
> And in the neighboring thread you just pointed out you used to just correct
> spelling fixes like this. I think it really depends on the workflow of the
> contributor. As I do the interdiff of the next version of the series against
> your tree I'll be likely to notice such typos in the content, but not in
> commit messages.

"git tbdiff" is your friend ;-)