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

[Junio C Hamano]

Stefan Beller  writes:

> On Tue, Aug 2, 2016 at 2:45 PM, Junio C Hamano  wrote:
>> Stefan Beller  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 ;-)
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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  wrote:
> Stefan Beller  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 [...]

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  and 

in its description. So I looked at the `stash` man page, which has
the options listed with the subcommands (and also has []
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Junio C Hamano]

Stefan Beller  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 [...]


> @@ -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] [--] [...]::
>   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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

  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 [--] [...]
 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] ...)
 '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 ] [--depth ] [--recursive]
  [--jobs ] [--] [...]
 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) ]
@@ -62,7 +62,7 @@ if you choose to go that route.
 
 COMMANDS
 
-add::
+add [-b ] [-f|--force] [--name ] [--reference ] 
[--depth ] [--]  []::
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] [--] [...]::
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 [--] [...]::
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|[--] ...)::
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 ] [--depth 
] [--recursive] [--jobs ] [--] [...]::
 +
 --
 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) ] [commit] [--] 
[...]::
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] ::
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] [--] [...]::
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

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html