From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 02 Aug 2016 21:45:27 GMT
Subject: Re: [PATCH 1/2] submodule documentation: add options to the subcommand
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>...]


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