git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH] add usage-strings ci check and amend remaining usage strings

From
Abhradeep Chakraborty via GitGitGadget <gitgitgadget@gmail.com>
Date
Feb 16, 2022, 17:02 UTC
Message-ID
<pull.1147.git.1645030949730.gitgitgadget@gmail.com>
From: Abhra303 <chakrabortyabhradeep79@gmail.com>

Usage strings for git (sub)command flags has a style guide that suggests - first letter should not capitalized (unless requied) and it should skip full-stop at the end of line. But there are some files where usage-strings do not follow the above mentioned guide. Moreover, there are no checks to verify if all usage strings are following the guide/convention or not.

Amend the usage strings that don't follow the convention/guide and add a `CI` check for checking the usage strings (whether the first letter is capital or it ends with full-stop). If the `check` find such strings then print those strings and return a non-zero status.

Also provide a script that takes an optional argument (a valid <tree> string), to check the usage strings in the given <tree> (`HEAD` is the default argument).

Signed-off-by: Abhradeep Chakraborty <chakrabortyabhradeep79@gmail.com>
---
    add usage-strings ci check and amend remaining usage strings
    
    This patch series completely fixes #636.
    
    The issue is about amending the usage-strings (for command flags such as
    -h, -v etc.) which do not follow the style convention/guide. There was a
    PR [https://github.com/gitgitgadget/git/pull/920] addressing this issue
    but as Johannes [https://github.com/dscho] said in his comment
    [https://github.com/gitgitgadget/git/issues/636#issuecomment-1018660439],
    there are some files that still have those kind of usage strings.
    Johannes also suggested to add a CI check under ci/test-documentation.sh
    to check the usage strings.
    
    So, in this patch, all remaining usage strings are corrected. I also
    added a check-usage-strings target in Makefile which can be used to
    check usage strings. It uses check-usage-strings.sh.
    
     1. If check-usage-strings.sh is run on a valid git repo - it will check
        the validity of usage-strings in the tree specified by an argument
        or in the HEAD if no argument provided.
     2. If the current repo is not a git repo (i.e. if it doesn't find any
        .git folder), it will check the usage string in the current root
        directory.
    
    For the first case, output of make check-usage-strings or
    ./check-usage-strings.sh would be similar to -
    
    HEAD:builtin/bisect--helper.c:1212                        N_("use <cmd>... to automatically bisect."), BISECT_RUN),
    HEAD:builtin/submodule--helper.c:1877            OPT__QUIET(&quiet, "Suppress output for cloning a submodule"),
    
    
    If an argument provided - ./check-usage-strings.sh 'v2.34.0' , it will
    search for usage-strings in v2.34.0 and v2.34.0 will be prefixed before
    filenames instead of HEAD.
    
    In the second case, output would be similar to -
    
    diff.c:5596                            N_("select files by diff type."),
    diff.c:5599               N_("Output to a specific file"),
    builtin/branch.c:666            OPT_BIT('C', NULL, &copy, N_("copy a branch, even if target exists."), 2),
    make: *** [check-usage-strings] Error 1
    
    
    Note in the last case - arguments provided to it will be useless.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1147%2FAbhra303%2Fusage_command_amend-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1147/Abhra303/usage_command_amend-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1147
 Makefile                    |  5 +++++
 builtin/bisect--helper.c    |  2 +-
 builtin/reflog.c            |  6 +++---
 builtin/submodule--helper.c |  2 +-
 check-usage-strings.sh      | 33 +++++++++++++++++++++++++++++++++
 ci/test-documentation.sh    |  1 +
 diff.c                      |  2 +-
 t/helper/test-run-command.c |  6 +++---
 8 files changed, 48 insertions(+), 9 deletions(-)
 create mode 100755 check-usage-strings.sh
diff --git a/Makefile b/Makefile
index 186f9ab6190..93faed51da0 100644
--- a/Makefile
+++ b/Makefile
@@ -3416,6 +3416,11 @@ check-docs::
 check-builtins::
 	./check-builtins.sh
 
+### Make sure all the usage strings follow usage string style guide
+#
+check-usage-strings::
+	./check-usage-strings.sh
+
 ### Test suite coverage testing
 #
 .PHONY: coverage coverage-clean coverage-compile coverage-test coverage-report
diff --git a/builtin/bisect--helper.c b/builtin/bisect--helper.c
index 28a2e6a5750..614d95b022c 100644
--- a/builtin/bisect--helper.c
+++ b/builtin/bisect--helper.c
@@ -1209,7 +1209,7 @@ int cmd_bisect__helper(int argc, const char **argv, const char *prefix)
 		OPT_CMDMODE(0, "bisect-visualize", &cmdmode,
 			 N_("visualize the bisection"), BISECT_VISUALIZE),
 		OPT_CMDMODE(0, "bisect-run", &cmdmode,
-			 N_("use <cmd>... to automatically bisect."), BISECT_RUN),
+			 N_("use <cmd>... to automatically bisect"), BISECT_RUN),
 		OPT_BOOL(0, "no-log", &nolog,
 			 N_("no log for BISECT_WRITE")),
 		OPT_END()
diff --git a/builtin/reflog.c b/builtin/reflog.c
index 85b838720c3..28372c5e2b5 100644
--- a/builtin/reflog.c
+++ b/builtin/reflog.c
@@ -600,7 +600,7 @@ static int cmd_reflog_expire(int argc, const char **argv, const char *prefix)
 		OPT_BIT(0, "updateref", &flags,
 			N_("update the reference to the value of the top reflog entry"),
 			EXPIRE_REFLOGS_UPDATE_REF),
-		OPT_BOOL(0, "verbose", &verbose, N_("print extra information on screen.")),
+		OPT_BOOL(0, "verbose", &verbose, N_("print extra information on screen")),
 		OPT_CALLBACK_F(0, "expire", &cmd, N_("timestamp"),
 			       N_("prune entries older than the specified time"),
 			       PARSE_OPT_NONEG,
@@ -613,7 +613,7 @@ static int cmd_reflog_expire(int argc, const char **argv, const char *prefix)
 			 N_("prune any reflog entries that point to broken commits")),
 		OPT_BOOL(0, "all", &do_all, N_("process the reflogs of all references")),
 		OPT_BOOL(1, "single-worktree", &all_worktrees,
-			 N_("limits processing to reflogs from the current worktree only.")),
+			 N_("limits processing to reflogs from the current worktree only")),
 		OPT_END()
 	};
 
@@ -736,7 +736,7 @@ static int cmd_reflog_delete(int argc, const char **argv, const char *prefix)
 		OPT_BIT(0, "updateref", &flags,
 			N_("update the reference to the value of the top reflog entry"),
 			EXPIRE_REFLOGS_UPDATE_REF),
-		OPT_BOOL(0, "verbose", &verbose, N_("print extra information on screen.")),
+		OPT_BOOL(0, "verbose", &verbose, N_("print extra information on screen")),
 		OPT_END()
 	};
 
diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
index c5d3fc3817f..9864ec1427d 100644
--- a/builtin/submodule--helper.c
+++ b/builtin/submodule--helper.c
@@ -1874,7 +1874,7 @@ static int module_clone(int argc, const char **argv, const char *prefix)
 		OPT_STRING(0, "depth", &clone_data.depth,
 			   N_("string"),
 			   N_("depth for shallow clones")),
-		OPT__QUIET(&quiet, "Suppress output for cloning a submodule"),
+		OPT__QUIET(&quiet, "suppress output for cloning a submodule"),
 		OPT_BOOL(0, "progress", &progress,
 			   N_("force cloning progress")),
 		OPT_BOOL(0, "require-init", &require_init,
diff --git a/check-usage-strings.sh b/check-usage-strings.sh
new file mode 100755
index 00000000000..a4028e0d00d
--- /dev/null
+++ b/check-usage-strings.sh
@@ -0,0 +1,33 @@
+{
+  if test -d ".git"
+  then
+    rev=${1:-"HEAD"}
+    for entry in $(git grep -l 'struct option .* = {$' "$rev" -- \*.c);
+    do
+      git show "$entry" |
+      sed -n '/struct option .* = {/,/OPT_END/{=;p;}' |
+      sed "N;s/^\\([0-9]*\\)\\n/$(echo "$entry" | sed 's/\//\\&/g'):\\1/";
+    done
+  else
+    for entry in $(grep -rl --include="*.c" 'struct option .* = {$' . );
+    do
+      cat "$entry" |
+      sed -n '/struct option .* = {/,/OPT_END/{=;p;}' |
+      sed "N;s/^\\([0-9]*\\)\\n/$(echo "$entry" | sed -e 's/\//\\&/g' -e 's/^\.\\\///'):\\1/";
+    done
+  fi
+} |
+grep -Pe '((?<!OPT_GROUP\(N_\(|OPT_GROUP\()"(?!GPG|DEPRECATED|SHA1|HEAD)[A-Z]|(?<!"|\.\.)\.")' |
+{
+  status=0
+  while read content;
+  do
+    if test -n "$content"
+    then
+      echo "$content";
+      status=1;
+    fi
+  done
+
+  exit $status
+}
diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh
index de41888430a..f66848dfc66 100755
--- a/ci/test-documentation.sh
+++ b/ci/test-documentation.sh
@@ -15,6 +15,7 @@ filter_log () {
 }
 
 make check-builtins
+make check-usage-strings
 make check-docs
 
 # Build docs with AsciiDoc
diff --git a/diff.c b/diff.c
index c862771a589..000be3bf232 100644
--- a/diff.c
+++ b/diff.c
@@ -5596,7 +5596,7 @@ static void prep_parse_options(struct diff_options *options)
 			       N_("select files by diff type"),
 			       PARSE_OPT_NONEG, diff_opt_diff_filter),
 		{ OPTION_CALLBACK, 0, "output", options, N_("<file>"),
-		  N_("Output to a specific file"),
+		  N_("output to a specific file"),
 		  PARSE_OPT_NONEG, NULL, 0, diff_opt_output },
 
 		OPT_END()
diff --git a/t/helper/test-run-command.c b/t/helper/test-run-command.c
index 913775a14b7..8f370cd89f1 100644
--- a/t/helper/test-run-command.c
+++ b/t/helper/test-run-command.c
@@ -221,9 +221,9 @@ static int quote_stress_test(int argc, const char **argv)
 	struct strbuf out = STRBUF_INIT;
 	struct strvec args = STRVEC_INIT;
 	struct option options[] = {
-		OPT_INTEGER('n', "trials", &trials, "Number of trials"),
-		OPT_INTEGER('s', "skip", &skip, "Skip <n> trials"),
-		OPT_BOOL('m', "msys2", &msys2, "Test quoting for MSYS2's sh"),
+		OPT_INTEGER('n', "trials", &trials, "number of trials"),
+		OPT_INTEGER('s', "skip", &skip, "skip <n> trials"),
+		OPT_BOOL('m', "msys2", &msys2, "test quoting for MSYS2's sh"),
 		OPT_END()
 	};
 	const char * const usage[] = {

base-commit: b80121027d1247a0754b3cc46897fee75c050b44

-- 
gitgitgadget
Next: Abhradeep Chakraborty
Message 1 of 58 in “add usage-strings ci check and amend remaining usage strings”
  1. add usage-strings ci check and amend remaining usage stringsAbhradeep Chakraborty via GitGitGadget, Feb 16, 2022
  2. Abhradeep ChakrabortyFeb 21, 2022
  3. Ævar Arnfjörð BjarmasonFeb 21, 2022
  4. Junio C HamanoFeb 21, 2022
  5. Abhradeep ChakrabortyFeb 21, 2022
  6. Ævar Arnfjörð BjarmasonFeb 21, 2022
  7. Johannes SchindelinFeb 22, 2022
  8. Ævar Arnfjörð BjarmasonFeb 22, 2022
  9. Julia LawallFeb 22, 2022
  10. Abhradeep ChakrabortyFeb 22, 2022
  11. Abhradeep ChakrabortyFeb 22, 2022
  12. Johannes SchindelinFeb 25, 2022
  13. Ævar Arnfjörð BjarmasonFeb 25, 2022
  14. Abhradeep ChakrabortyFeb 26, 2022
  15. Julia LawallFeb 26, 2022
  16. Johannes SchindelinFeb 25, 2022
  17. Julia LawallFeb 25, 2022
  18. Ævar Arnfjörð BjarmasonFeb 25, 2022
  19. Abhradeep ChakrabortyFeb 22, 2022
  20. add usage-strings check and amend remaining usage stringsAbhradeep Chakraborty via GitGitGadget, Feb 22, 2022
  21. Eric SunshineFeb 22, 2022
  22. Abhradeep ChakrabortyFeb 23, 2022
  23. Junio C HamanoFeb 23, 2022
  24. Eric SunshineFeb 23, 2022
  25. Abhradeep ChakrabortyFeb 24, 2022
  26. 0/2 add usage-strings ci check and amend remaining usage stringsAbhradeep Chakraborty via GitGitGadget, Feb 23, 2022
  27. 1/2 amend remaining usage strings according to style guideAbhra303 via GitGitGadget, Feb 23, 2022
  28. 2/2 parse-options.c: add style checks for usage-stringsAbhradeep Chakraborty via GitGitGadget, Feb 23, 2022
  29. 0/2 add usage-strings ci check and amend remaining usage stringsAbhradeep Chakraborty via GitGitGadget, Feb 25, 2022
  30. 1/2 amend remaining usage strings according to style guideAbhradeep Chakraborty via GitGitGadget, Feb 25, 2022
  31. 2/2 parse-options.c: add style checks for usage-stringsAbhradeep Chakraborty via GitGitGadget, Feb 25, 2022
  32. Junio C HamanoFeb 25, 2022
  33. Abhradeep ChakrabortyFeb 25, 2022
  34. Junio C HamanoFeb 25, 2022
  35. Abhradeep ChakrabortyFeb 26, 2022
  36. Johannes SchindelinFeb 25, 2022
  37. Abhradeep ChakrabortyFeb 25, 2022
  38. Junio C HamanoFeb 26, 2022
  39. Junio C HamanoFeb 26, 2022
  40. Abhradeep ChakrabortyFeb 26, 2022
  41. Junio C HamanoFeb 27, 2022
  42. Abhradeep ChakrabortyFeb 28, 2022
  43. Junio C HamanoFeb 28, 2022
  44. Ævar Arnfjörð BjarmasonFeb 28, 2022
  45. Abhradeep ChakrabortyMar 1, 2022
  46. Junio C HamanoMar 1, 2022
  47. Johannes SchindelinMar 1, 2022
  48. Abhradeep ChakrabortyMar 3, 2022
  49. Junio C HamanoMar 3, 2022
  50. Abhradeep ChakrabortyMar 4, 2022
  51. Johannes SchindelinMar 7, 2022
  52. Abhradeep ChakrabortyMar 8, 2022
  53. parse-options: make parse_options_check() test-onlyJunio C Hamano, Mar 1, 2022
  54. Ævar Arnfjörð BjarmasonMar 1, 2022
  55. Junio C HamanoMar 1, 2022
  56. Ævar Arnfjörð BjarmasonMar 2, 2022
  57. Junio C HamanoMar 2, 2022
  58. Ævar Arnfjörð BjarmasonMar 2, 2022

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.