Re: [PATCH] Documentation/submodule: add command references and update options
- From
Jens Lehmann <jens.lehmann@web.de>
- Date
- Jul 26, 2011, 18:44 UTC
- Message-ID
- <4E2F0AF7.2070306@web.de>
- In-Reply-To
- <7vmxg2qf0j.fsf@alter.siamese.dyndns.org>
Am 25.07.2011 22:30, schrieb Junio C Hamano:
Show 19 quoted lines
> Jens Lehmann <Jens.Lehmann@web.de> writes: > >> @@ -131,7 +137,7 @@ update:: >> + >> If the submodule is not yet initialized, and you just want to use the >> setting as stored in .gitmodules, you can automatically initialize the >> -submodule with the --init option. >> +submodule with the '--init' option. > > Don't we want to use > > the `--init` option > > instead for consistency? After all, that is what the users actually type. > > $ git grep -e "\`--[a-z]" Documentation/ | wc -l > 287 > $ git grep -e "'--[a-z]" Documentation/ | wc -l > 132
Fine by me, I just followed the style I found there. Will change all option names (including those who are using '--init' right now) to `--init` in the next iteration.
Show 20 quoted lines
>> @@ -140,11 +146,14 @@ summary:: >> 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 >> - index or working tree (switched by --cached) are shown. If the option >> - --files is given, show the series of commits in the submodule between >> + index or working tree (switched by '--cached') are shown. If the option >> + '--files' is given, show the series of commits in the submodule between >> the index of the super project and the working tree of the submodule >> - (this option doesn't allow to use the --cached option or to provide an >> + (this option doesn't allow to use the '--cached' option or to provide an >> explicit commit). >> ++ >> +Using the '--submodule=log' option with linkgit:git-diff[1] will provide the >> +same information. > > I am not a huge fan of these extra paragraphs, especially in reality it is > not "provide the same" but "the same and a lot of other". > > I dunno.
I added them because in a discussion with Marc it became apparent that users can't learn about what diff and status can do for them by checking the submodule man-page. But you are right about "the same and a lot of other", I will update the wording of those paragraphs.
Maybe someone else has a better idea how to inform users that git diff and status can tell you a lot (and sometimes even more than the submodule script) about the state submodules are in?