Re: [PATCH 2/2] documentation: add documentation for 'git version'

From: Matthias Aßhauer <mha1993@live.de>
Date: Sep 13, 2021, 11:46 UTC
Message-ID: <AM0PR04MB6019DD0BBD77BEA85771B9E9A5D99@AM0PR04MB6019.eurprd04.prod.outlook.com>
In-Reply-To: <87r1ds4t3w.fsf@evledraar.gmail.com>

On Mon, 13 Sep 2021, Ævar Arnfjörð Bjarmason wrote:

Show 50 quoted lines

>
> On Mon, Sep 13 2021, Matthias Aßhauer via GitGitGadget wrote:
>
>> From: =?UTF-8?q?Matthias=20A=C3=9Fhauer?= <mha1993@live.de>
>>
>> While 'git version' is probably the least complex git command,
>> it is a non-experimental user-facing builtin command. As such
>> it should have a help page.
>
> This looks good
>
>> Signed-off-by: Matthias Aßhauer <mha1993@live.de>
>> ---
>>  Documentation/git-version.txt | 35 +++++++++++++++++++++++++++++++++++
>>  1 file changed, 35 insertions(+)
>>  create mode 100644 Documentation/git-version.txt
>>
>> diff --git a/Documentation/git-version.txt b/Documentation/git-version.txt
>> new file mode 100644
>> index 00000000000..c7d6b496c8d
>> --- /dev/null
>> +++ b/Documentation/git-version.txt
>> @@ -0,0 +1,35 @@
>> +git-version(1)
>> +==============
>> +
>> +NAME
>> +----
>> +git-version - Display version information about Git
>> +
>> +
>> +SYNOPSIS
>> +--------
>> +[verse]
>> +'git version' [--build-options]
>>
>> +
>> +DESCRIPTION
>> +-----------
>> +
>> +With no options given, the version of 'git' is printed
>> +on the standard output.
>
> Good
>
>> +
>> +If the option `--build-options` is given, information about how git was built is
>> +printed on the standard output in addition to the version number.
>
> Let's just cover this in the OPTIONS section you added...

Ok, I can absolutely do that.

Show 12 quoted lines

>
>> +Note that `git --version` is identical to `git version` because the
>> +former is internally converted into the latter.
>
> Probably better to just have a new section:
>
> SEE ALSO
> --------
>
> linkgit:git[1]'s `--version` option, which dispatches to this command.
>
>

I've closely based this on git-help.txt, since `--help` and `--version` both are options that get internally converted to the corresponding command.

Show 19 quoted lines

>> +OPTIONS
>> +-------
>> +--build-options::
>> +	Prints out additional information about how git was built for diagnostic
>> +	purposes.
>> +
>> +GIT
>> +---
>> +Part of the linkgit:git[1] suite
>
>
> It would also be good to update git.txt, which now says:
>
>    Prints the Git suite version that the git program came from
>
> To say e.g. "Dispatches to linkgit:git-version[1], prints the git
> program version".
>
> Or something like that, i.e. to cross-link the two.

That makes sense. Should we do the same for '--help'?

Best regards

Matthias