| Message ID | d3635cbfd6ef0d47ebf28c516476dcd0b718afd4.1631531219.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | documentation: handle non-existing html pages and document 'git version' | expand |
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... > +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. > +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.
On Mon, 13 Sep 2021, Ævar Arnfjörð Bjarmason wrote: > > 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. > >> +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. >> +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
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: >> +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. Hmph, I am not sure if this is a good move. If we are not giving any more information than what the reader has already learned from this page, other than "git --version" does the same thing, we probably do not want to do this. By seeing also that other page, the user will not learn anything new about "git version". If a related "git --version-something-else" is described over there and may fill the need the reader had when visiting this page, that is a different story, but I do not think it is the case. >> +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". This one may be a good idea, I think. "git --version --build-options" also works and we do not want to clutter git[1] with descriptions on suboptions of "git version". If we are not doing so for the "--help" option in git[1], we should do so as well. Thanks.
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. + +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. + +Note that `git --version` is identical to `git version` because the +former is internally converted into the latter. + +OPTIONS +------- +--build-options:: + Prints out additional information about how git was built for diagnostic + purposes. + +GIT +--- +Part of the linkgit:git[1] suite