[v3,00/13] Fixes to trailer test script, help text, and documentation

Message

Philippe Blain via GitGitGadget Sept. 7, 2023, 10:19 p.m. UTC

This series contains various fixes to the trailer code. They pertain to
fixes to the test script, the command line help text for the
interpret-trailers builtin, and the documentation.

Patch 1 is the most important as it does cleanups in the tests where we used
'git config' in a test case without cleaning up that state for the next
test. This makes the tests self-contained, making it easier to add new tests
anywhere along the script, without worrying about previously-set implicit
state. These test cleanups exposed lots of cases where the test cases are
mutating more configuration state than is necessary to test the specific
behavior in the test; however such extraneous configurations were not
cleaned up to make these patches easier to review (again, we are not
changing any behavior and we are also not changing what the test cases
themselves purport to do).

Note that Patch 1 was originally a 22-commit series, but was squashed
together to make it easier to see the final diff for each test case. You can
see the 22-commit breakdown at
https://github.com/listx/git/tree/backup-trailer-22-commit-breakdown

Patch 3 adds some tests to check the behavior of '--no-if-exists' and
'--no-if-missing', which weren't previously tested. It also adds
similarly-themed test cases for '--no-where' which only had 1 test case for
it.

The other patches aren't as important, but are included here because I think
they are too small to include in a separate series.


Updates in v3
=============

 * Fix t0450 failure due to mismatch between the updated documentation which
   uses " or " and the help text of the interpret-trailers command.


Updates in v2
=============

 * Many additional patches to fix the help text and docs. No changes to any
   of the patches touching the actual tests (that is, Patch 1 and 3 have
   stayed the same, other than a rewording of the commit message for Patch
   1).
 * Of these new patches, I think the last one (about <keyAlias>) is the most
   important as it resolves a longtime ambiguity about what a <token> can
   be.

Linus Arver (13):
  trailer tests: make test cases self-contained
  trailer test description: this tests --where=after, not --where=before
  trailer: add tests to check defaulting behavior with --no-* flags
  trailer doc: narrow down scope of --where and related flags
  trailer: trailer location is a place, not an action
  trailer --no-divider help: describe usual "---" meaning
  trailer --parse help: expose aliased options
  trailer --only-input: prefer "configuration variables" over "rules"
  trailer --parse docs: add explanation for its usefulness
  trailer --unfold help: prefer "reformat" over "join"
  trailer doc: emphasize the effect of configuration variables
  trailer doc: separator within key suppresses default separator
  trailer doc: <token> is a <key> or <keyAlias>, not both

 Documentation/git-interpret-trailers.txt | 183 ++++----
 builtin/interpret-trailers.c             |  12 +-
 t/t7513-interpret-trailers.sh            | 506 +++++++++++++++++++----
 3 files changed, 545 insertions(+), 156 deletions(-)


base-commit: 1b0a5129563ebe720330fdc8f5c6843d27641137
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1564%2Flistx%2Ftrailer-fixes-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1564/listx/trailer-fixes-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1564

Range-diff vs v2:

  1:  1623dd000dd =  1:  1623dd000dd trailer tests: make test cases self-contained
  2:  f680e76de84 =  2:  f680e76de84 trailer test description: this tests --where=after, not --where=before
  3:  4b5c458ef43 =  3:  4b5c458ef43 trailer: add tests to check defaulting behavior with --no-* flags
  4:  0df12c5c2dd =  4:  0df12c5c2dd trailer doc: narrow down scope of --where and related flags
  5:  040766861e2 =  5:  040766861e2 trailer: trailer location is a place, not an action
  6:  3e58b6f5ea2 =  6:  3e58b6f5ea2 trailer --no-divider help: describe usual "---" meaning
  7:  d1780a0127a =  7:  d1780a0127a trailer --parse help: expose aliased options
  8:  5cfff52da8f =  8:  5cfff52da8f trailer --only-input: prefer "configuration variables" over "rules"
  9:  ef6b77016cd =  9:  ef6b77016cd trailer --parse docs: add explanation for its usefulness
 10:  a08d78618ba = 10:  a08d78618ba trailer --unfold help: prefer "reformat" over "join"
 11:  4db823ac354 = 11:  4db823ac354 trailer doc: emphasize the effect of configuration variables
 12:  66087eaf5bd = 12:  66087eaf5bd trailer doc: separator within key suppresses default separator
 13:  7b66cf29d29 ! 13:  0b9525db5a0 trailer doc: <token> is a <key> or <keyAlias>, not both
     @@ Documentation/git-interpret-trailers.txt: trailer.<token>.command::
       
       EXAMPLES
       --------
     +
     + ## builtin/interpret-trailers.c ##
     +@@
     + 
     + static const char * const git_interpret_trailers_usage[] = {
     + 	N_("git interpret-trailers [--in-place] [--trim-empty]\n"
     +-	   "                       [(--trailer <token>[(=|:)<value>])...]\n"
     ++	   "                       [(--trailer (<key>|<keyAlias>)[(=|:)<value>])...]\n"
     + 	   "                       [--parse] [<file>...]"),
     + 	NULL
     + };