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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 2, 2016, 21:45 UTC
Message-ID: <xmqqtwf2c0aw.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20160802182152.20637-1-sbeller@google.com>

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>...]

Show 9 quoted lines

> @@ -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