documentation: handle non-existing html pages and document 'git version'
cover documentation: handle non-existing html pages and document 'git version'
These two patches are grouped as one patch series, because they arose from the same Git for Windows issue [1], but they can be reviewed or applied independent from one another.
[1] https://github.com/git-for-windows/git/issues/3308
Matthias Aßhauer (2):
help: make sure local html page exists before calling external
processes
documentation: add documentation for 'git version'
Documentation/git-version.txt | 35 +++++++++++++++++++++++++++++++++++ builtin/help.c | 9 ++++++++- t/t0012-help.sh | 7 +++++++ 3 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 Documentation/git-version.txt
base-commit: 8463beaeb69fe0b7f651065813def4aa6827cd5d
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1038%2Frimrul%2Fdoc-version-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1038/rimrul/doc-version-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1038
Signature · 1 line
gitgitgadget
PATCH 1/2 help: make sure local html page exists before calling external processes
From: =?UTF-8?q?Matthias=20A=C3=9Fhauer?= <[email protected]>
We already check that git.html exists, regardless of the page the user wants to open. Additionally checking wether the requested page exists gives us a smoother user experience when it doesn't.
When calling a git command and there is an error, most users reasonably expect git to produce an error message on the standard error stream, but in this case we pass the filepath to git web--browse wich passes it on to a browser (or a helper programm like xdg-open or start that should in turn open a browser) without any error and many GUI based browsers or helpers won't output such a message onto the standard error stream.
Especialy the helper programs tend to show the corresponding error message in a message box and wait for user input before exiting. This leaves users in interactive console sessions without an error message in their console, without a console prompt and without the help page they expected.
The performance cost of the additional stat should be negliggible compared to the two or more pocesses that we spawn after the checks.
--- builtin/help.c | 9 ++++++++- t/t0012-help.sh | 7 +++++++ 2 files changed, 15 insertions(+), 1 deletion(-)
builtin/help.c +8 -1
@@ -467,11 +467,18 @@ static void get_html_page_path(struct strbuf *page_path, const char *page)if (!html_path) html_path = to_free =system_path (GIT_HTML_PATH ); -/* Check that we have a git documentation directory. */ +/* +* Check that we have a git documentation directory and the page we're +* looking for exists. +*/ if (!strstr (html_path,"://" )) {if (stat (mkpath ("%s/git.html" , html_path), &st) || !S_ISREG (st.st_mode))die ("'%s': not a documentation directory." , html_path); +if (stat (mkpath ("%s/%s.html" , html_path, page), &st) + || !S_ISREG (st.st_mode)) +die ("'%s/%s.html': documentation file not found." , + html_path, page); }strbuf_init (page_path,0 );
t/t0012-help.sh +7 -0
@@ -77,6 +77,13 @@ test_expect_success 'generate builtin list' ' git --list-cmds=builtins >builtins ' +test_expect_success 'git help fails for non-existing html pages' ' + configure_help && + mkdir html-doc && + touch html-doc/git.html && + test_must_fail git -c help.htmlpath=html-doc help status +' + while read builtin do test_expect_success "$builtin can handle -h" '
Signature · 1 line
gitgitgadget
Re: [PATCH 1/2] help: make sure local html page exists before calling external processes
Quoted 2 lines · Matthias Aßhauer via GitGitGadget
We already check that git.html exists, regardless of the page the user wants to open. Additionally checking wether the requested page exists gives us a
s/wether/whether/
Quoted 5 lines
smoother user experience when it doesn't.
When calling a git command and there is an error, most users reasonably expect git to produce an error message on the standard error stream, but in this case we pass the filepath to git web--browse wich passes it on to a browser (or a
s/wich/which/
Quoted 1 line
helper programm like xdg-open or start that should in turn open a browser)
s/programm/program/
Quoted 4 lines
without any error and many GUI based browsers or helpers won't output such a message onto the standard error stream.
Especialy the helper programs tend to show the corresponding error message in
s/Especialy/Especially/
Quoted 5 lines
a message box and wait for user input before exiting. This leaves users in interactive console sessions without an error message in their console, without a console prompt and without the help page they expected.
The performance cost of the additional stat should be negliggible compared to
s/negliggible/negligible/
Quoted 1 line
the two or more pocesses that we spawn after the checks.
s/pocesses/processes/
Quoted 1 line
Signed-off-by Matthias Aßhauer <[email protected]>
Re: [PATCH 1/2] help: make sure local html page exists before calling external processes
Quoted 30 lines · Eric Sunshine
Quoted 2 lines · Matthias Aßhauer via GitGitGadget
We already check that git.html exists, regardless of the page the user wants to open. Additionally checking wether the requested page exists gives us a
s/wether/whether/
Quoted 5 lines
smoother user experience when it doesn't.
When calling a git command and there is an error, most users reasonably expect git to produce an error message on the standard error stream, but in this case we pass the filepath to git web--browse wich passes it on to a browser (or a
s/wich/which/
Quoted 1 line
helper programm like xdg-open or start that should in turn open a browser)
s/programm/program/
Quoted 4 lines
without any error and many GUI based browsers or helpers won't output such a message onto the standard error stream.
Especialy the helper programs tend to show the corresponding error message in
s/Especialy/Especially/
Quoted 4 lines
a message box and wait for user input before exiting. This leaves users in interactive console sessions without an error message in their console, without a console prompt and without the help page they expected.
Quoted 10 lines
Quoted 1 line
The performance cost of the additional stat should be negliggible compared to
s/negliggible/negligible/
Quoted 1 line
the two or more pocesses that we spawn after the checks.
s/pocesses/processes/
Quoted 1 line
Signed-off-by Matthias Aßhauer <[email protected]>
Thank you for pointing out this embarrassing amount of typos. I've fixed them for the next version.
Best regards
Matthias
Re: [PATCH 1/2] help: make sure local html page exists before calling external processes
In reply to Matthias Aßhauer via GitGitGadget"Matthias Aßhauer via GitGitGadget" <[email protected]>
Quoted 11 lines · writes:
builtin/help.c +2
-1@@ -467,11 +467,18 @@ static void get_html_page_path(struct strbuf *page_path, const char *page)if (!html_path) html_path = to_free =system_path (GIT_HTML_PATH ); -/* Check that we have a git documentation directory. */ +/* +* Check that we have a git documentation directory and the page we're
builtin/help.c static void get_html_page_path(struct strbuf *page_path, const char *page) · line 481
Quoted 10 lines
builtin/help.c +6
-0+* looking for exists. +*/ if (!strstr (html_path,"://" )) {if (stat (mkpath ("%s/git.html" , html_path), &st) || !S_ISREG (st.st_mode))die ("'%s': not a documentation directory." , html_path); +if (stat (mkpath ("%s/%s.html" , html_path, page), &st) + || !S_ISREG (st.st_mode)) +die ("'%s/%s.html': documentation file not found." , + html_path, page);
I do not remember why we did not originally use the "page" information and only checked "git.html", but because the "page" is ultimately what the end-user will see, I wonder if it even makes sense to still check "git.html" anymore.
If the request were "git help -w git", the new check added here would catch the missing page, and for "git help -w log", it is unfair to call the directory that we successfully found the "git-log.html" in as "not a doc directory" only because it is for whatever reason is missing "git.html" next to it.
It seems that this check dates back to 482cce82 (help: make 'git-help--browse' usable outside 'git-help'., 2008-02-02); even in the context of that commit, I think it would have been better to check for the generated page_path instead of git.html, so I actually prefer to see the existing hardcoded check for git.html replaced with the new check.
Thanks.
Quoted 21 lines
builtin/help.c +0
-0}strbuf_init (page_path,0 );t/t0012-help.sh +7
-0@@ -77,6 +77,13 @@ test_expect_success 'generate builtin list' ' git --list-cmds=builtins >builtins ' +test_expect_success 'git help fails for non-existing html pages' ' + configure_help && + mkdir html-doc && + touch html-doc/git.html && + test_must_fail git -c help.htmlpath=html-doc help status +' + while read builtin do test_expect_success "$builtin can handle -h" '
PATCH 2/2 documentation: add documentation for 'git version'
In reply to Matthias Aßhauer via GitGitGadgetFrom: =?UTF-8?q?Matthias=20A=C3=9Fhauer?= <[email protected]>
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.
--- Documentation/git-version.txt | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 Documentation/git-version.txt
Documentation/git-version.txt new file +35 -0
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH 2/2] documentation: add documentation for 'git version'
Quoted 5 lines · Matthias Aßhauer via GitGitGadget
From: =?UTF-8?q?Matthias=20A=C3=9Fhauer?= <[email protected]>
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
Quoted 21 lines
Signed-off-by Matthias Aßhauer <[email protected]>--- Documentation/git-version.txt | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 Documentation/git-version.txtDocumentation/git-version.txt new file +9
-0@@ -0,0 +1,35 @@ +git-version(1) +============== + +NAME +---- +git-version - Display version information about Git + + +SYNOPSIS
Documentation/git-version.txt line 19
Quoted 10 lines
Documentation/git-version.txt new file +9
-0+-------- +[verse] +'git version' [--build-options] + +DESCRIPTION +----------- + +With no options given, the version of 'git' is printed +on the standard output.
Good
Documentation/git-version.txt line 22
Quoted 3 lines
Documentation/git-version.txt new file +3
-0+ +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...
Documentation/git-version.txt line 25
Quoted 2 lines
Documentation/git-version.txt new file +2
-0+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.
Documentation/git-version.txt line 35
Quoted 9 lines
Documentation/git-version.txt new file +9
-0+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.
Re: [PATCH 2/2] documentation: add documentation for 'git version'
Quoted 45 lines · Ævar Arnfjörð Bjarmason
Quoted 5 lines · Matthias Aßhauer via GitGitGadget
From: =?UTF-8?q?Matthias=20A=C3=9Fhauer?= <[email protected]>
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
Quoted 21 lines
Signed-off-by Matthias Aßhauer <[email protected]>--- Documentation/git-version.txt | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 Documentation/git-version.txtDocumentation/git-version.txt new file +9
-0@@ -0,0 +1,35 @@ +git-version(1) +============== + +NAME +---- +git-version - Display version information about Git + + +SYNOPSISDocumentation/git-version.txt line 19
Quoted 10 lines
Documentation/git-version.txt new file +9
-0+-------- +[verse] +'git version' [--build-options] + +DESCRIPTION +----------- + +With no options given, the version of 'git' is printed +on the standard output.Good
Quoted 5 lines
Documentation/git-version.txt line 22
Quoted 3 lines
Documentation/git-version.txt new file +3
-0+ +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.
Quoted 6 lines
Documentation/git-version.txt line 25
Quoted 3 lines
Documentation/git-version.txt new file +2
-0+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:
Quoted 6 lines
SEE ALSO
--------linkgit:git[1]'s
--versionoption, 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.
Quoted 13 lines
Documentation/git-version.txt line 35
Quoted 9 lines
Documentation/git-version.txt new file +9
-0+OPTIONS +------- +--build-options:: + Prints out additional information about how git was built for diagnostic + purposes. + +GIT +--- +Part of the linkgit:git[1] suiteIt would also be good to update git.txt, which now says:
Quoted 6 lines
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
Re: [PATCH 2/2] documentation: add documentation for 'git version'
In reply to Ævar Arnfjörð BjarmasonQuoted 9 lines · Ævar Arnfjörð Bjarmason
Documentation/git-version.txt line 25
Quoted 2 lines
Documentation/git-version.txt new file +2
-0+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
--versionoption, 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.
Quoted 13 lines
Documentation/git-version.txt line 35
Quoted 9 lines
Documentation/git-version.txt new file +9
-0+OPTIONS +------- +--build-options:: + Prints out additional information about how git was built for diagnostic + purposes. + +GIT +--- +Part of the linkgit:git[1] suiteIt would also be good to update git.txt, which now says:
Quoted 4 lines
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.
v2 cover documentation: handle non-existing html pages and document 'git version'
In reply to Matthias Aßhauer via GitGitGadgetThese two patches are grouped as one patch series, because they arose from the same Git for Windows issue [1], but they can be reviewed or applied independent from one another.
One interesting oddity I found while preparing V2: git --version --help gets converted to git version --help which then calls git help version, but git --help --version gets converted to git help --version and git help doesn't know what to do with --version.
[1] https://github.com/git-for-windows/git/issues/3308
Changes since V1:
* fixed various typos in the log message of patch 1
* changed patch 1 to just check the requested page instead of both the requested page and git.html
* moved the test up before the "generate builtin list" test
* reworked the test slightly
* added a second test
* removed the redundant description of --build-options from the DESCRIPTION section
* added a small paragraph to Documentation/git.txt that links to the new git version page (like we already do for git help)
Matthias Aßhauer (2):
help: make sure local html page exists before calling external
processes
documentation: add documentation for 'git version'
Documentation/git-version.txt | 28 ++++++++++++++++++++++++++++ Documentation/git.txt | 4 ++++ builtin/help.c | 9 ++++++--- t/t0012-help.sh | 16 ++++++++++++++++ 4 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 Documentation/git-version.txt
base-commit: 8463beaeb69fe0b7f651065813def4aa6827cd5d
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1038%2Frimrul%2Fdoc-version-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1038/rimrul/doc-version-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1038
Range-diff vs v1:
1: 8674d67a439 ! 1: c55360272d5 help: make sure local html page exists before calling external processes
@@ Metadata
## Commit message ##
help: make sure local html page exists before calling external processes
- We already check that git.html exists, regardless of the page the user wants
- to open. Additionally checking wether the requested page exists gives us a
- smoother user experience when it doesn't.
+ We check that git.html exists, regardless of the page the user wants to open.
+ Checking whether the requested page exists instead gives us a smoother user
+ experience in two use cases:
+
+ 1) The requested page doesn't exist
When calling a git command and there is an error, most users reasonably expect git to produce an error message on the standard error stream, but in this case
- we pass the filepath to git web--browse wich passes it on to a browser (or a
- helper programm like xdg-open or start that should in turn open a browser)
+ we pass the filepath to git web--browse which passes it on to a browser (or a
+ helper program like xdg-open or start that should in turn open a browser)
without any error and many GUI based browsers or helpers won't output such a message onto the standard error stream.
- Especialy the helper programs tend to show the corresponding error message in
+ Especially the helper programs tend to show the corresponding error message in
a message box and wait for user input before exiting. This leaves users in interactive console sessions without an error message in their console, without a console prompt and without the help page they expected.
- The performance cost of the additional stat should be negliggible compared to
- the two or more pocesses that we spawn after the checks.
+ 2) git.html is missing for some reason, but the user asked for some other page
+
+ We currently refuse to show any local html help page when we can't find
+ git.html. Even if the requested help page exists. If we check for the requested
+ page instead, we can show the user all available pages and only error out on
+ those that don't exist.
@@ builtin/help.c: static void get_html_page_path(struct strbuf *page_path, const c
- /* Check that we have a git documentation directory. */
+ /*
-+ * Check that we have a git documentation directory and the page we're
-+ * looking for exists.
++ * Check that the page we're looking for exists.
+ */
if (!strstr(html_path, "://")) {
- if (stat(mkpath("%s/git.html", html_path), &st)
- || !S_ISREG(st.st_mode))
- die("'%s': not a documentation directory.", html_path);
+- if (stat(mkpath("%s/git.html", html_path), &st)
+ if (stat(mkpath("%s/%s.html", html_path, page), &st)
-+ || !S_ISREG(st.st_mode))
+ || !S_ISREG(st.st_mode))
+- die("'%s': not a documentation directory.", html_path);
+ die("'%s/%s.html': documentation file not found.",
+ html_path, page);
}
@@ builtin/help.c: static void get_html_page_path(struct strbuf *page_path, const c
strbuf_init(page_path, 0);
## t/t0012-help.sh ##
-@@ t/t0012-help.sh: test_expect_success 'generate builtin list' '
- git --list-cmds=builtins >builtins
+@@ t/t0012-help.sh: test_expect_success 'git help -g' '
+ test_i18ngrep "^ tutorial " help.output
'
+test_expect_success 'git help fails for non-existing html pages' '
+ configure_help &&
-+ mkdir html-doc &&
-+ touch html-doc/git.html &&
-+ test_must_fail git -c help.htmlpath=html-doc help status
++ mkdir html-empty &&
++ test_must_fail git -c help.htmlpath=html-empty help status &&
++ test_must_be_empty test-browser.log
+'
+
- while read builtin
- do
- test_expect_success "$builtin can handle -h" '
++test_expect_success 'git help succeeds without git.html' '
++ configure_help &&
++ mkdir html-with-docs &&
++ touch html-with-docs/git-status.html &&
++ git -c help.htmlpath=html-with-docs help status &&
++ echo "html-with-docs/git-status.html" >expect &&
++ test_cmp expect test-browser.log
++'
++
+ test_expect_success 'generate builtin list' '
+ git --list-cmds=builtins >builtins
+ '
2: d3635cbfd6e ! 2: bc9a4534f5b documentation: add documentation for 'git version'
@@ Commit message
it is a non-experimental user-facing builtin command. As such it should have a help page.
+ Both git help and git version can be called as options
+ (--help/--version) that internally get converted to the
+ corresponding command. Add a small paragraph to
+ Documentation/git.txt describing how these two options
+ interact with each other and link to this help page for the
+ sub-options that --version can take. Well, currently there
+ is only one sub-option, but that could potentially increase
+ in future versions of Git.
+
## Documentation/git-version.txt (new) ##
@@ Documentation/git-version.txt (new)
+----
+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. ++With no options given, the version of 'git' is printed on the standard output.
+
+Note that git --version is identical to git version because the +former is internally converted into the latter.
@@ Documentation/git-version.txt (new)
+OPTIONS
+-------
+--build-options::
-+ Prints out additional information about how git was built for diagnostic
++ Include additional information about how git was built for diagnostic
+ purposes.
+
+GIT
+---
+Part of the linkgit:git[1] suite
+
+ ## Documentation/git.txt ##
+@@ Documentation/git.txt: OPTIONS
+ -------
+ --version::
+ Prints the Git suite version that the 'git' program came from.
+++
++This option is internaly converted to git version ... and accepts ++the same options as the linkgit:git-version[1] command. If --help is ++also given, it takes precedence over --version.
+
+ --help::
+ Prints the synopsis and a list of the most commonly used
Signature · 1 line
gitgitgadget
PATCH v2 1/2 help: make sure local html page exists before calling external processes
From: =?UTF-8?q?Matthias=20A=C3=9Fhauer?= <[email protected]>
We check that git.html exists, regardless of the page the user wants to open. Checking whether the requested page exists instead gives us a smoother user experience in two use cases:
1) The requested page doesn't exist
When calling a git command and there is an error, most users reasonably expect git to produce an error message on the standard error stream, but in this case we pass the filepath to git web--browse which passes it on to a browser (or a helper program like xdg-open or start that should in turn open a browser) without any error and many GUI based browsers or helpers won't output such a message onto the standard error stream.
Especially the helper programs tend to show the corresponding error message in a message box and wait for user input before exiting. This leaves users in interactive console sessions without an error message in their console, without a console prompt and without the help page they expected.
2) git.html is missing for some reason, but the user asked for some other page
We currently refuse to show any local html help page when we can't find git.html. Even if the requested help page exists. If we check for the requested page instead, we can show the user all available pages and only error out on those that don't exist.
--- builtin/help.c | 9 ++++++--- t/t0012-help.sh | 16 ++++++++++++++++ 2 files changed, 22 insertions(+), 3 deletions(-)
builtin/help.c +6 -3
@@ -467,11 +467,14 @@ static void get_html_page_path(struct strbuf *page_path, const char *page)if (!html_path) html_path = to_free =system_path (GIT_HTML_PATH ); -/* Check that we have a git documentation directory. */ +/* +* Check that the page we're looking for exists. +*/ if (!strstr (html_path,"://" )) { -if (stat (mkpath ("%s/git.html" , html_path), &st) +if (stat (mkpath ("%s/%s.html" , html_path, page), &st) || !S_ISREG (st.st_mode)) -die ("'%s': not a documentation directory." , html_path); +die ("'%s/%s.html': documentation file not found." , + html_path, page); }strbuf_init (page_path,0 );
t/t0012-help.sh +16 -0
@@ -73,6 +73,22 @@ test_expect_success 'git help -g' ' test_i18ngrep "^ tutorial " help.output ' +test_expect_success 'git help fails for non-existing html pages' ' + configure_help && + mkdir html-empty && + test_must_fail git -c help.htmlpath=html-empty help status && + test_must_be_empty test-browser.log +' + +test_expect_success 'git help succeeds without git.html' ' + configure_help && + mkdir html-with-docs && + touch html-with-docs/git-status.html && + git -c help.htmlpath=html-with-docs help status && + echo "html-with-docs/git-status.html" >expect && + test_cmp expect test-browser.log +' + test_expect_success 'generate builtin list' ' git --list-cmds=builtins >builtins '
Signature · 1 line
gitgitgadget
PATCH v2 2/2 documentation: add documentation for 'git version'
In reply to Matthias Aßhauer via GitGitGadgetFrom: =?UTF-8?q?Matthias=20A=C3=9Fhauer?= <[email protected]>
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.
Both git help and git version can be called as options (--help/--version) that internally get converted to the corresponding command. Add a small paragraph to Documentation/git.txt describing how these two options interact with each other and link to this help page for the sub-options that --version can take. Well, currently there is only one sub-option, but that could potentially increase in future versions of Git.
--- Documentation/git-version.txt | 28 ++++++++++++++++++++++++++++ Documentation/git.txt | 4 ++++ 2 files changed, 32 insertions(+) create mode 100644 Documentation/git-version.txt
Documentation/git-version.txt new file +28 -0
@@ -0,0 +1,28 @@ +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. + +Note that `git --version` is identical to `git version` because the +former is internally converted into the latter. + +OPTIONS +------- +--build-options:: + Include additional information about how git was built for diagnostic + purposes. + +GIT +--- +Part of the linkgit:git[1] suite
Documentation/git.txt +4 -0
@@ -41,6 +41,10 @@ OPTIONS ------- --version:: Prints the Git suite version that the 'git' program came from. ++ +This option is internaly converted to `git version ...` and accepts +the same options as the linkgit:git-version[1] command. If `--help` is +also given, it takes precedence over `--version`. --help:: Prints the synopsis and a list of the most commonly used
Signature · 1 line
gitgitgadget
Is "make check-docs" useful anymore?
Quoted 61 lines · Matthias Aßhauer via GitGitGadget
From: =?UTF-8?q?Matthias=20A=C3=9Fhauer?= <[email protected]>
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.
Both
git helpandgit versioncan be called as options (--help/--version) that internally get converted to the corresponding command. Add a small paragraph toDocumentation/git.txtdescribing how these two options interact with each other and link to this help page for the sub-options that--versioncan take. Well, currently there is only one sub-option, but that could potentially increase in future versions of Git.Signed-off-by Matthias Aßhauer <[email protected]>--- Documentation/git-version.txt | 28 ++++++++++++++++++++++++++++ Documentation/git.txt | 4 ++++ 2 files changed, 32 insertions(+) create mode 100644 Documentation/git-version.txtDocumentation/git-version.txt new file +28
-0@@ -0,0 +1,28 @@ +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. + +Note that `git --version` is identical to `git version` because the +former is internally converted into the latter. + +OPTIONS +------- +--build-options:: + Include additional information about how git was built for diagnostic + purposes. + +GIT +--- +Part of the linkgit:git[1] suiteDocumentation/git.txt +0
-0
Documentation/git.txt OPTIONS · line 50
Quoted 10 lines
Documentation/git.txt +4
-0@@ -41,6 +41,10 @@ OPTIONS ------- --version:: Prints the Git suite version that the 'git' program came from. ++ +This option is internaly converted to `git version ...` and accepts +the same options as the linkgit:git-version[1] command. If `--help` is +also given, it takes precedence over `--version`. --help:: Prints the synopsis and a list of the most commonly used
I didn't notice until after it hit master that this caused a regression in "make check-docs":
$ make -s check-docs
removed but documented: git-versionThe "fix" is rather easy, i.e. adding "git-version" to the whitelist.
But I wondered about $subject, i.e. we want to run the "lint" part, but do we really need something reminding us that there isn't a mapping between Documentation/*.txt and *.o files present at the top-level?
That whole part seems to have been some "reminder to document" addition in 8c989ec5288 (Makefile: $(MAKE) check-docs, 2006-04-13).
If we're going to keep it in pretty much its current form then the CI integration added in b98712b9aa9 (travis-ci: build documentation, 2016-05-04) seems rather useless when it comes to this, i.e. we should either adjust it to exit non-zero, or check if we've got output under "make -s" and fail the check then.
Re: Is "make check-docs" useful anymore?
Quoted 11 lines · Ævar Arnfjörð Bjarmason
I didn't notice until after it hit master that this caused a regression in "make check-docs":
$ make -s check-docs removed but documented: git-versionThe "fix" is rather easy, i.e. adding "git-version" to the whitelist.
But I wondered about $subject, i.e. we want to run the "lint" part, but do we really need something reminding us that there isn't a mapping between
Documentation/*.txtand *.o files present at the top-level?
There were multiple things check-docs wanted to catch originally.
- commands not referred to from the main page
- a new command added without documentation
- an old command removed while leaving documentation
It may be that we no longer remove commands, so the last check may be less useful.
Quoted 4 lines
If we're going to keep it in pretty much its current form then the CI integration added in
b98712b9aa9(travis-ci: build documentation, 2016-05-04) seems rather useless when it comes to this, i.e. we should either adjust it to exit non-zero,...
Yes, that is a good thing to do.
Thanks.