README_DOCS.rst: update tg prev and tg next usage summary

[topgit/pro.git] / t / README-TESTLIB

Testing Library
===============

The point of the testing library (available by sourcing the
test-lib.sh file) is to assist with rapidly writing robust
tests that produce TAP-compliant output.  (For a quick primer
on TAP see the README file in the section "TAP - A Quick Overview".)


----------------------------
Why Use the Testing Library?
----------------------------

Because it:

* hopefully helps to allow tests to be written more quickly
* catches common failures (signal exits, not found etc.)
* avoids reproducing commonly needed code in every test
* prevents unwanted "other" lines from ending up in the TAP output
* allows test results to be aggregated without using "prove"
* supports easier test debugging


---------------
Getting Started
---------------

Check out the `README` file for a quick overview of everything in the test
directory and a brief overview of TAP.

This file, `README-TESTLIB`, serves as a reference of available variables,
options and functions in the testing library that can be used by test writers
to create tests.  This file does not, however, provide any "how-to" instruction
as that's reserved for the `README-WRITING-TESTS` file.

The `README-WRITING-TESTS` file describes how to quickly get started writing
tests using the testing library and should be perused by anyone who finds the
simplistic example in the `README` file to be insufficient.  It does not,
however, serve as a comprehensive reference for the testing library.

To quickly find the testing library function and/or variable needed refer to
the [Quick Reference] section below.


-------------
Running Tests
-------------

Note there is a difference between the way test scripts passed to the various
test_expect/test_tolerate functions behave compared to Git's testing library.
In this testing library the scripts passed to those functions are evaluated
inside a subshell (test_eval_inner_ uses (...) instead of {...}).  This is
done intentionally so that any errors in the test itself do not abort the
testing process (and yes, that can happen).  It also allows `set -e` to be
activated by default in the subshell (which it is).  As a side effect, this
means that variables set in such test scripts DO NOT PERSIST after running the
test scripts.  The `test_when_finished` function can be used to raise up some
information out of the (possibly nested) subshell as it runs after the
subtests's subshell has exited -- this is an enhancement compared to Git's
version of `test_when_finished` which doesn't support any subshells at all.

See the TESTLIB_TEST_NO_SUBSHELL variable to disable (NOT recommended) the use
of a subshell.


---------------
Quick Reference
---------------

Variable                        | Description
--------------------------------|----------------------------------------------
TESTLIB_DIRECTORY               | directory where testing library code lives
EMPTY_DIRECTORY                 | empty directory with no write permission
TEST_DIRECTORY                  | directory with tNNNN-*.sh scripts to run
TEST_HELPER_DIRECTORY           | directory with "helpers" (auto-added to PATH)
TEST_OUTPUT_DIRECTORY           | test output ends up in here
TRASH_DIRECTORY                 | test specific temporary "trash" directory
TRASHTMP_DIRECTORY              | test specific temporary `test_get_temp` dir
TESTLIB_SKIP_TESTS              | test suite wide test/subtest skipping pats
TESTLIB_NO_TOLERATE             | `test_tolerate_failure` means expect success
TESTLIB_TEST_CHAIN_LINT         | can be used to disable `&&` chaining test
TESTLIB_TEST_NO_SUBSHELL        | prevent subshell for subtests (do not use)
TESTLIB_TEST_TAP_ONLY           | limit output to (almost) only TAP lines
TEST_NO_CREATE_REPO             | suppress initial `test_create_repo .`
color                           | either "" (--no-color) or "--color" (--color)
skip_all                        | `test_done` skip value for `1..0` plan
test_auh                        | `--allow-unrelated-histories` if Git >= 2.9
test_description                | must be non-empty before `. ./test-lib.sh`
test_external_has_tap           | avoid changing -- will suppress TAP lines
test_hash_algo                  | either `sha1` or `sha256` (only if supported)
test_tick                       | last commit timestamp used see same function
this_test                       | basename $0 | sed 's/-*//' (usually tNNNN)

TAP function                    | Description
--------------------------------|----------------------------------------------
test_done                       | uncounted plan line and counts (call last)
test_expect_success             | expect success from a script (no #TODO)
test_expect_failure             | expect failure from a script (with #TODO)
test_external                   | test external command
test_external_without_stderr    | test external command & require empty stderr
test_plan                       | output TAP plan line (call first)
test_tolerate_failure           | expect success or failure from a script

Utility function                | Description
--------------------------------|----------------------------------------------
die                             | fatally exit the test (or subshell) right now
error                           | Bail out! now and kill all further testing
git_init                        | git -c init.defaultBranch=master init "$@"
list_contains                   | check comma-separated list against wildcards
sane_unset                      | safe unset for broken sh implementations
say                             | say_color info ... shortcut
say_color                       | output in the named (special names) color
say_color_tap                   | if $HARNESS_ACTIVE always output w/o color
say_tap                         | say_color_tap info ... shortcut
test_at_end_hook_               | called by `test_done` default is `:`
test_clear_when_finished        | make code run just after current subtest exit
test_cmp                        | fail if two text files do not match
test_cmp_bin                    | fail if two binary files do not match
test_cmp_rev                    | fail if two Git revspecs resolve differently
test_commit                     | make a new commit optionally tagging it
test_config                     | make test_when_finished reverted config mod
test_config_global              | like `test_config` but `--global` config
test_copy_bytes                 | transfer specified # of bytes from in to out
test_create_repo                | create dir (if not exists) and `git_init` it
test_debug                      | with `--debug` run args otherwise nop
test_diff                       | fancy (same semantics) `test_cmp` using git
test_dir_is_empty               | verbose fail if directory not empty
test_env                        | like /usr/bin/env but works for functions too
test_expect_code                | fail unless command has specified exit status
test_get_temp                   | create a new, unique empty temp file (or dir)
test_have_prereq                | check for a prereq
test_line_count                 | overblown `test` plus `wc` utility
test_match_signal               | bad bad bad ksh
test_merge                      | `test_tick` & `git merge` & `git tag` shortcut
test_might_fail                 | succeeds for all but abnormal exits
test_must_be_empty              | verbose fail if `test -s ...` is true
test_must_fail                  | succeed for all non-0 and non-abnormal exits
test_path_is_dir                | verbose failure if `test -d ...` fails
test_path_is_file               | verbose failure if `test -f ...` fails
test_path_is_missing            | verbose failure if `test -e ...` fails
test_pause                      | interactive $SHELL if `--verbose` else error
test_seq                        | shell-only version of 1 and 2 arg seq 
test_set_editor                 | properly quote value and set+export EDITOR
test_set_prereq                 | set specified prereq to true
test_skip_or_die                | prefer `test_plan 0 <msg>` or `error <msg>`
test_tick                       | set or increment(+60) the `test_tick` var
test_tristate                   | reset variable to `true`, `false` or `auto`
test_unconfig                   | safe `git config --unset-all` when unset
test_when_finished              | run code right after current subtest exits
test_write_lines                | overblown `printf '%s\n'` shortcut
verbose                         | verbosely show a command's failures
wc                              | whitespace safe version of wc
write_script                    | make executable sh script from stdin
yes                             | 99 times max shell-only version of yes


---------
Variables
---------

- TESTLIB_DIRECTORY

    This directory contains the testing library source code scripts (i.e.
    `test-lib.sh`, `test-lib-main.sh` and `test-lib-functions.sh`).  This
    variable is exported.  Should be constant for any given test suite run.
    If not set, defaults to the real directory of
    "${TEST_DIRECTORY:-.}/test-lib.sh" (if test-lib.sh is a symblic link
    somewhere else then that somewhere else directory will be the actual
    default for TESTLIB_DIRECTORY, NOT the result of dirname).

- EMPTY_DIRECTORY

    This directory will be empty (i.e. no files in it) _AND_ will *NOT* have
    any write permissions enabled.  Usually this is "$TESTLIB_DIRECTORY/empty".

- TEST_DIRECTORY

    This directory contains the test scripts to be run (e.g. `t1234-foo.sh`)
    and will often be the same as TESTLIB_DIRECTORY.  It is also exported.
    Should be constant for any given test suite run.  This directory MUST
    contain a `test-lib.sh` file even if it's only a symbolic link to the
    real `test-lib.sh` file (n.b. it _MUST NOT_ be a hard link).

- TEST_HELPER_DIRECTORY

    The test helpers are located in here.  It defaults to
    "$TEST_DIRECTORY/helper" if not set and that directory exists.  It is
    automatically added to the `PATH`.  Helper scripts should use this to
    locate any auxilliary files they might need to use that are checked into
    version control alongside them.  This variable is also exported.

- TEST_OUTPUT_DIRECTORY

    This is the directory containing output from the tests.  It defaults to
    TEST_DIRECTORY.  Another exported variable.  Should be constant for any
    given test suite run.

- TRASH_DIRECTORY

    This directory is named after the specific test being run, for example,
    `trash directory.t0000-foo.sh`.  By default it's located in the
    TEST_OUTPUT_DIRECTORY but the `--root` option to a test script (options
    are parsed by the "`. ./test-lib.sh`" line) can change that.  Using the
    `--root` option to specify a directory on a RAM disk can accelerate
    testing.  This variable changes for every test and the directory it
    specifies is automatically created and destroyed (`test-lib.sh` makes
    that happen).

- TRASHTMP_DIRECTORY

    This directory is named after the specific test being run, for example,
    `trash tmp directory.t0000-foo.sh`.  By default it's located in the
    TEST_OUTPUT_DIRECTORY but the `--root` option to a test script (options
    are parsed by the "`. ./test-lib.sh`" line) can change that.  Using the
    `--root` option to specify a directory on a RAM disk can accelerate
    testing.  This variable changes for every test and the directory it
    specifies is automatically created and destroyed (`test-lib.sh` makes
    that happen).

    However, unlike TRASH_DIRECTORY, this directory is created on-demand the
    first time the `test_get_temp` function is called (or a lazy prereq is
    evaluated) and so should not be used directly.  Rather it exists primarily
    to support creation of temporary test files that live completely outside
    of TRASH_DIRECTORY and so can be created and used without concern about
    any possible unintended consequences of temporary files lying around in
    the TRASH_DIRECTORY (or a subdirectory thereof) causing unexpected test
    results.

- TESTLIB_SKIP_TESTS

    This variable can be used to skip whole tests or parts of tests.  It should
    contain a whitespace-separated list of shell patterns.  If any of the
    pattern(s) match the test or subtest is skipped.  The patterns are matched
    against:

       1. the basename of the test with the first `'-'` and everything
          following stripped off

       2. value from (1) suffixed with `'.'` and the number of the subtest
          where the first subtest is number 1

    If the test file is `t/t1234-hello-there.sh` then the value used for (1) is
    "t1234".  For (2) and the second subtest the value is "t1234.2".

    So setting TESTLIB_SKIP_TESTS="t1234 t1235.[235]" will skip test t1234
    entirely and subtests 2, 3 and 5 of t1235.

- TESTLIB_NO_TOLERATE

    If this is set to any non-empty value then all `test_tolerate_failure`
    calls are turned into `test_expect_success` calls.

- TESTLIB_TEST_CHAIN_LINT

    This variable defaults to true (any non-empty value).  When true it results
    in a fatal "Bail out!" error if any test script code (the last argument to
    the `test_expect_success` function for example) does not have all of its
    statements connected by `&&`.  This variable may be set to the string "0"
    _BEFORE_ sourcing `test-lib.sh` to disable this.  Alternatively, the
    checker can be "fooled" by enclosing code in `{ ` ... `;}` or putting it in
    a separate function that's called.

- TESTLIB_TEST_NO_SUBSHELL

    Normally the various test_expect_.../test_tolerate_... functions eval the
    test scripts they've been passed inside a subshell so that unexpected
    failures do not abort the test process.  This precludes, however, making
    any lasting variable changes in the passed in script.  This is a good
    thing.  However, if `TESTLIB_TEST_NO_SUBSHELL` is set to a non-empty string
    then the scripts will NOT be eval'd in a subshell.  Try to avoid using
    this.  Note that it may be toggled in between
    test_expect.../test_tolerate_... calls to only enable it for one test for
    example.

    Use of this variable to disable subtest subshells is deprecated and may go
    away at some point!  Avoid this if at all possible!  The
    `test_when_finished` function (possibly combined with `test_get_temp`) can
    be used to raise information out of a subtest subshell when required.

- TESTLIB_TEST_TAP_ONLY

    Setting this to a value other than empty or `0` suppresses extraneous
    failure output (such as the script).  Incompatible with verbose mode (but
    allowed with verbose log mode).  If set to the special value -1 it will
    auto-disable when verbose mode is used.

    Note that when TESTLIB_TEST_TAP_ONLY is enabled one additional line will
    be output for each failure showing the file and line number, but _only_ if
    the line number is available.  This extra line can be suppressed by using
    `--quiet` when TESTLIB_TEST_TAP_ONLY is enabled.

    Set `TESTLIB_TEST_TAP_ONLY = -1` in your `config.mak` and get happy.

- TESTLIB_GIT_DEFAULT_HASH

    Select the default hash algorithm for Git to use when creating new
    repositories.  If this is not set, it defaults to `sha1`.

    Essentially TESTLIB_GIT_DEFAULT_HASH provides a default `--hash=<hash>`
    option for the individual tests if no explicit `--hash=<hash>` option has
    been given.

    If TESTLIB_GIT_DEFAULT_HASH is not the empty string ("") and is neither
    `sha1` nor `sha256` a fatal error will occur.

    If TESTLIB_GIT_DEFAULT_HASH is set to `sha256` and the version of Git is
    not at least version 2.29.0, a fatal error will occur.

- TEST_NO_CREATE_REPO

    Since the focus of the testing library is on Git or Git-related software
    all "trash directory...."s are initialized as a non-bare empty Git
    repository by default.  Setting `TEST_NO_CREATE_REPO` _BEFORE_ sourcing
    the `test-lib.sh` testing library file will instead result in the "trash"
    directory for the test just being an empty directory instead.  The
    function `test_create_repo` can always be used to easily create a
    repository (or two or more) if desired.

- color

    Set automatically or explicity using the `--color` or `--no-color` options.
    It will be the empty string if "no color" is in effect or it will be the
    string "--color" if "color" is in effect.  It can therefore be directly
    used as an argument to git commands when producing debugging output.

- skip_all

    If set to a non-empty value before calling the `test_done` function and
    zero tests have been run, then the value will be appended to the output
    `1..0 # SKIP ` plan line.  If the test matches `$TESTLIB_SKIP_TESTS` when
    `./test-lib.sh` is sourced, `skip_all` will be set to a suitable value and
    `test_done` called immediately.

- test_auh

    Will automatically be set to empty unless the detected Git version is at
    least version 2.9 in which case it will be set to the value
    `--allow-unrelated-histories`.  Inteded for use with `git merge`.  The
    `test_merge` function automatically supplies this.

- test_description

    This variable _must_ be set to a non-empty value _before_ sourcing the
    `test-lib.sh` script.  Other than checking for non-empty, there are no
    requirements for the value.  It is only used by the `-h`|`--help` options
    (which are parsed when `test-lib.sh` is sourced).  The only formatting
    that occurs before it is output is that leading and trailing blank lines
    are trimmed off.  Recommended format is like a Git check in comment with
    one summary line and then any optional body separated from the summary
    line by one blank line if present.  Ideally it should explain enough about
    the test so that if the test is failing someone other than the test author
    can debug the problem.

- test_external_has_tap

    The default setting for this variable is `0` and should normally be left
    set to `0`.  Setting it to any other value causes the output of test plan
    and test result TAP lines to be suppressed.  It can be useful when one
    testing library test is using the testing library to run a set of tests
    thereby preventing the recursive testing library invocation from upsetting
    the TAP output of the parent.

- test_hash_algo

    This will be set to either `sha1` or `sha256`.  It indicates which hash
    algorithm Git will use for `git_init` and `test_asv`.  The initial value
    will be taken from `TESTLIB_GIT_DEFAULT_HASH` with `sha1` being used if
    that is not set.  The `--hash=<hash>` option can be used to run a test with
    a specific hash algorithm (overriding any `TESTLIB_GIT_DEFAULT_HASH`
    value).  However, an error will be generated if an attempt is made to use
    the `sha256` algorithm with a version of Git prior to the 2.29.0 release.

- test_tick

    Initially unset.  Records the last unix epoch seconds value that was used
    by the `test_tick` function to set both the `GIT_COMMITTER_DATE` and
    `GIT_AUTHOR_DATE` variables.  Note that the `test_tick` function always
    appends " -0700" to the value of "$test_tick" when constructing the value
    for `GIT_COMMITTER_DATE` and `GIT_AUTHOR_DATE`.

    If `test_tick` is unset or empty when the `test_tick` function is called
    then it will be set to 1112911993 (2005-04-07 15:13:13 -0700) and that
    value used.  Otherwise it will be advanced by 60 and the resulting value
    used.

    See also the description of the `test_tick` utility function below.

- this_test

    This variable is set automatically by the ". ./test-lib.sh" line.

    The value of "$this_test" is the basename of the current test file upto
    but excluding the first "-" in the name.  For example "t/t1000-it-works.sh"
    has a "$this_test" value of "t1000".  Since tests are expected to be
    located in the "$TEST_DIRECTORY" directory, any test that needs to make use
    of auxilliary files should locate them in a "$TEST_DIRECTORY/$this_test"
    directory that is checked in alongside the test so in the case of the
    aforementioned "t/t1000-it-works.sh" this might be the directory structure
    if two auxilliary files "aux1" and "aux2" were present:

        t/t1000-it-works.sh
        t/t1000/aux1
        t/t1000/aux2

    And all three of them would be checked into version control.


------------
Test Options
------------

When `test-lib.sh` is sourced, it parses the options passed to the test.  When
running tests via the Makefile, setting "TESTLIB_TEST_OPTS" will pass those
options to _every_ test run by the Makefile.

* --chain-lint | --no-chain-lint

    Set TESTLIB_TEST_CHAIN_LINT to 1 (`--chain-lint`) or 0 (`--no-chain-lint`).
    See the description of TESTLIB_TEST_CHAIN_LINT above for details.

* --color | --no-color

    Override automatic color detection (color output is normally enabled when
    output is to a terminal that supports color sequences) and activate
    (--color) or deactivate (--no-color) color output.  Note that when the
    environment variable `HARNESS_ACTIVE` is non-empty, color is ALWAYS
    SUPPRESSED when TAP lines are output and the `#` first character of
    comment lines also has its color suppressed in that case.

* -d | --debug

    Normally any command preceded by `test_debug` becomes a nop.  (The testing
    library itself does not use `test_debug` anywhere.)  With `--debug` these
    lines are activated and actually run instead of being nops.

    Using this option also prevents the temporary trash directory from being
    removed even for a successful test.

* --hash=<hash>

    The value of <hash> must be either `sha1` or `sha256`.  If this option is
    not used, the `TESTLIB_GIT_DEFAULT_HASH` environment variable will select
    the hash to be used and if that's not set, `sha1` will be used.

    If this option is used, then the `TESTLIB_GIT_DEFAULT_HASH` environment
    variable will be set to <hash> and exported to fully effect an override.

    Attempting to use `sha256` with a version of Git prior to version 2.29.0
    will cause a fatal error.

* -h | --help

    Show the `$test_description` to standard output and `exit 0`.  NO TAP lines
    of any kind are output when using this option (nor are the
    $test_description lines prefixed with the `#` comment character).

* -i | --immediate

    When `--immediate` is used, if a test_expect_success... etc. call fails
    then `exit 1` immediately after showing the `not ok` and quoted (with
    leading `#` characters) test script.

* -l | --long | --long-tests | --expensive

    Set and export `TESTLIB_TEST_LONG=t`.  The `EXPENSIVE` prereq checks for
    this and only succeeds when `TESTLIB_TEST_LONG` is non-empty.

* -q | --quiet | --no-quiet

    Suppresses some output lines such as "ok" (only when NOT running under a
    harness) and various output from test_external... functions.  Mainly
    useful to produce more compact output when NOT running under a TAP harness.

    Ignored if `--verbose` is also active.

    When combined with `--run` the skipping test message(s) that would
    otherwise be output when tests are skipped by a `--run` option are
    suppressed unless $HARNESS_ACTIVE.

    Use of `--run` will implicitly partially activate the `--quiet` option
    unless the `--no-quiet` option is also given.  The "partially" part means
    that it will only suppress the skipping test messages but not any other
    messages that would ordinarily be suppressed with an explicit `--quiet`.

    Use an explicit `--quiet` or `--no-quiet` to leave "partially quiet" mode
    when the `--run` option is in use.

* --root=<path>

    Causes the "trash directories" to be created as subdirectories of `<path>`
    instead of as subdirectories of `$TEST_OUTPUT_DIRECTORY`.  Specifying a
    RAM disk location as `<path>` can significantly speed up testing.

* --run=<run-list> | -r <run-list>

    The <run-list> must contain comma or whitespace separated "selectors".  But
    note that when using "TESTLIB_TEST_OPTS" only comma separated will work.

    A selector must match either !?\d+ or !?\d*-\d* which is to say it's either
    <num> or <num>- or -<num> or <num>-<num> optionally prefixed with `!`.  The
    "<num>-" form is a shortcut for <num>-infinity and the "-<num>" form is a
    shortcut for "1-<num>".

    If the first (or only) selector is prefixed with `!` then it's an exclusion
    list otherwise it's an inclusion list.

    The "selectors" are processed in left to right order and if the number of
    the subtest matches the range it will be run if the selector was NOT
    prefixed with `!` otherwise it will be excluded.

    An "inclusion" list includes and runs ONLY those subtests that are
    specifically matched by a selector NOT prefixed with `!`.  (Note that
    a subsequent selector can again exclude a previously included match and
    vice versa).

    An "exclusion" list runs everything except tests that are specifically
    excluded by a match.  In other words an "exclusion" list is just a shortcut
    to avoid adding a "1-" selector to the front of <run-list>.

    For example, "1-4,!3" will run only subtests 1, 2 and 4 but so will
    "1,2,4".  On the other hand, "!3,1-4" will run ALL subtests except 3
    (because it's equivalent to "1-,!3,1-4") as will just "!3".

    Using the `--run` option (with a non-empty list) implicitly partially
    activates the `--quiet` option (see the desciption of the `--quiet`
    option) and moves the test plan line to the end (if there was a `test_plan`
    call at the beginning), but adding an explicit `--no-quiet` (or `--quiet`)
    will override all that.

* --tap-only | --no-tap-only

    Set `TESTLIB_TEST_TAP_ONLY` to `1` or `0` respectively.  See the
    description for `TESTLIB_TEST_TAP_ONLY`.  Use of ``--tap-only`` is
    incompatible with ``--verbose`` unless ``--verbose-log`` is also used.
    Does _not_ cause `TESTLIB_TEST_TAP_ONLY` to be exported (unless it already
    was exported).

* --tee

    All standard output and standard error from running the test is copied to
    $TEST_OUTPUT_DIRECTORY/test-results/$(basename $0 .sh).out and as a side
    effect standard error is redirected to standard out.  The final exit code
    is written to $TEST_OUTPUT_DIRECTORY/test-results/$(basename $0 .sh).exit
    as well.

    This is accomplished by running another copy of the test script and
    redirecting both its standard output and standard error through the `tee`
    utility and when that copy exits, so too will the "tee" process and it will
    then use the same exit code as its exit code (unless something went wrong
    and no exit code was recorded in which case it exits with a result of 1).

    The environment variable TESTLIB_TEST_TEE_OUTPUT_FILE is set (and exported)
    to the name of the file the output is being "tee"'d into.

* -v | --verbose

    When `--verbose` is used the `test_pause` function will actually pause
    a test by entering a subshell and `test_external_without_stderr` will show
    both stdout and stderr output on failure.  Test scripts passed to the
    test_expect_success... functions are run with standard output and standard
    error left unchanged (normally it's sent to /dev/null).

    Automatically enabled by `-x`.

    Note that `--verbose` is not allowed when $HARNESS_ACTIVE.

* --verbose-log

    Enables the `--tee` option and arranges for the standard output and
    standard error that are enabled by `--verbose` to end up in the same log
    file that `--tee` creates while not disrupting the output going to the
    test harness.

    This setting supersedes `--verbose` in that if both are given the output
    ends up in the log but not on normal standard output or standard error.

    Also if `--verbose-only=...` is used together with this option then only
    the subtests selected by the `--verbose-only` option value will have their
    output captured into the log -- the other subtests will have it sent to
    /dev/null.

    Note that `--verbose-log` *IS* compatible with $HARNESS_ACTIVE.

* --verbose-only=<run-list>

    The current subtest number (sub tests are numbered starting at 1) is
    matched against <run-list> (see description for `--run` option) and if
    there's a match then `--verbose` is active for that subtest and if there is
    *NOT* a match then `--verbose` is NOT active for that subtest.

    For example, `--verbose-only="1-3,5"` will enable verbose for
    subtests 1, 2, 3 and 5 and will DISABLE verbose mode for subtests
    4,6,7,8,9,10,11,12,13,14,15 etc.

    Using this option with a non-empty <run-list> value completely supersedes
    any explicit `--verbose` option (before or after).  (Using it with an empty
    value just silently has no effect.)

    Note that `--verbose-only=...` is not allowed when $HARNESS_ACTIVE unless
    `--verbose-log` is also used.

* -x | --xtrace

    Set the `--verbose` option and temporarily enable the shell's `set -x`
    option while evaluating the scripts passed to test_expect_success....

    Note, however, that tracing will be suppressed unless verbose is also
    enabled.  Normally that will always be the case since `-x` also enables
    `--verbose`.  However, if `--verbose-only` is used then verbose will be
    toggled on a per-subtest basis and as a result the `-x` option will only
    be in effect for subtests selected by the `--verbose-only=...` option.

    Note that since this option sets `--verbose` it's not normally allowed
    when $HARNESS_ACTIVE but setting `--verbose-log` will allow it and send the
    output to the log file.


------------------
TAP Test Functions
------------------

These are functions that are intended to ultimately emit either a TAP test plan
line or a TAP test (aka "subtest") result line.

These functions are intended to be called from the main body of a test script
(e.g. t-????-*.sh) after having sourced the `./test-lib.sh` script.


Test Plan Functions
~~~~~~~~~~~~~~~~~~~

The purpose of these functions is to output the single, required, TAP test
plan line.  Additionally the `test_done` function performs some extra work.

- test_done

    Outputs a TAP test plan line.

    MUST be called AFTER any test result functions.  (TAP supports outputting
    a test plan line either _before all_ test result lines or _after all_
    test result lines.)

    It may be tempting to output the plan line without using this function.
    Don't do that.  Failure to use this function will result in test cleanup
    functions failing to run and the test results aggregation provided by the
    testing library breaking.

    If `$test_external_has_tap` is set to something other than `0` (the
    default) then no test plan line will be output but normal test cleanup will
    take place.

    If `$skip_all` is set to a non-empty value AND 0 tests were run then the
    `$skip_all` message will be appended to a `1..0 # SKIP ' line (which is,
    again, suppressed if `$test_external_has_tap` is not `0`).

    The `test_done` function then calls either `exit 0` if there were no
    unexpected failures or `exit 1` if there were.  Just before calling
    `exit 0` (but _not_ `exit 1`) the `test_at_end_hook_` function is called
    which, by default, always succeeds and does nothing but can be re-defined
    by a test script if such a hook is needed.

    Note that if the test name appears in `$TESTLIB_SKIP_TESTS` (see the
    description above) then `$skip_all` is automatically set to a suitable
    value and `test_done` is called immediately when `./test-lib.sh` is
    sourced.

    The `test_done` function DOES NOT RETURN!  It _always_ ends up calling
    exit with an exit status and therefore _never_ returns to the caller!

- test_plan <count> <count==0> <optional> <alternate> <skip> <msg> <here>

    This function allows a test plan line to be output first.  If `$skip_all`
    is set it just passes through to `test_done`.  Otherwise it outputs the
    test plan line using the first argument as the total test count and then
    sets `test_wrote_plan_count=$1` so that the required subsequent call to
    `test_done` does not write a second test plan line.  (But if the value of
    `$test_external_has_tap` is not 0 it will not output the test plan line.)

    If the argument is 0, then `skip_all` will be set to the following
    arguments (or a suitable default if there are no following arguments) and
    `test_done` will be called immediately (which will cause an immediate
    exit of the test script at that point).

    Using `test_plan` is inconvenient in that the number of subtests in the
    file must be known in advance.  Sometimes that's not possible if the number
    of tests to be run varies depending on test conditions.  Other times it's
    just damn inconvenient to have to count all those subtests.  ;)

    To document that a `test_plan` number has been deliberately omitted, a
    single argument of `?` can be used (e.g. `test_plan '?'` -- the "?" needs
    to be quoted in some fashion to avoid wildcard expansion).  Using the
    value "`?`" has the same effect as not having any `test_plan` line at all
    but documents the intent not to have one.

    If `test_plan` is never called (and the entire test was not skipped as a
    result of a `TESTLIB_SKIP_TESTS` setting) a message urging addition of a
    `test_plan` call will be output.  With support for a count of `?`, it's
    always possible to add a `test_plan` call to the script.

    Outputting the test plan line in advance makes those fancy test harnesses
    (like `prove`) show a "1/n" progress rather than "1/?" which is nice to
    have and that is the reason the `test_plan` function is provided (and the
    prodding message output if it's not been called at `test_done` time).

    Also if a different number of tests are run than are planned the overall
    test will fail with an error which provides yet another test of the test
    script itself which is not available without a call to `test_plan`.

    The `test_done` function MUST STILL BE CALLED at the end of the test script
    even when `test_plan` is used at the beginning otherwise test aggregation
    and test cleanup will fail to take place!  The only exception is when a
    `test_plan 0` (possibly with optional arguments) call is _always_ used as
    it will implicitly call `test_done` before returning (and therefore never
    actually return at all).

    Note that if it's not already clear from the description, use of the
    `test_plan` function is completely optional, but use of `test_done` is not.


Test Result Functions
~~~~~~~~~~~~~~~~~~~~~

The purpose of these functions is to output one `ok` or `not ok` TAP test
result line each time they're called.

All of these functions take an optional first argument which is a whitespace
and/or comma separated list of prerequisites that must be present or the
test will be skipped.  This is shown as `[<prereqs>]`.  Each prereq in the
list may be optionally prefixed with a single `!` to require the item *not*
be present.

All of these functions expect the next argument to be a brief test description
that will be used in the `ok` or `not ok` output line.  This is shown as
`<desc>`.

The "external" functions expect two additional arguments which are the
"external" command to be run and its single argument (use `eval` and a suitable
string to work around this requirement for exactly two arguments).  These are
shown as `<cmd>` `<arg>`.

The non-"external" functions expect one additional argument which is the
test script to be "eval"'d.  However, if the test script argument is `-` then
the test script will be read from standard input (allowing use of a HERE doc to
simplify quoting issues), but this is slightly inefficient so avoid using it
unless it's really needed.  This is shown as `<script>`.  Note that scripts are
normally "eval"'d inside a subshell to avoid side-effects and uncaught
failures, but this can be altered with the `TESTLIB_TEST_NO_SUBSHELL` variable
(see description above).

Test scripts are "eval"'d as the last line of a function so they may exit early
by using a `return` statement or, if `$TESTLIB_TEST_NO_SUBSHELL` is _NOT_ set
(which is the default), by using an `exit` statement.

- test_expect_success [<prereqs>] <desc> <script>

    If <prereqs> are present and unsatisfied an "ok # skip" line is output and
    the <script> is _not_ "eval"'d.  Otherwise, the <script> is "eval"'d and if
    it succeeds (exit code is 0) then this subtest succeeds and outputs an "ok"
    line otherwise it outputs a "not ok" line.

- test_expect_failure [<prereqs>] <desc> <script>

    If <prereqs> are present and unsatisfied an "ok # skip" line is output and
    the <script> is _not_ "eval"'d.  Otherwise, the <script> is "eval"'d and if
    it fails (exit code is _not_ 0) then this subtest outputs a "not ok # todo"
    line.  If the script succeeds a "ok # todo" line is output which will
    ultimately produce some warnings and/or complaints about a "known breakage"
    vanishing or "todo passing".  See the `test_tolerate_failure` function to
    avoid this.

- test_tolerate_failure [<prereqs>] <desc> <script>

    If <prereqs> are present and unsatisfied an "ok # skip" line is output and
    the <script> is _not_ "eval"'d.  Otherwise, the <script> is "eval"'d and if
    it fails (exit code is _not_ 0) then this subtest outputs a "not ok # todo"
    line.  If the script succeeds a plain "ok" line is output (which avoids
    any complaints about "vanishing" breakages).  However, if the variable
    `TESTLIB_NO_TOLERATE` is non-empty all `test_tolerate_failure` calls are
    turned into `test_expect_success` calls instead (meaning a failure causes
    a regular `not ok` to be output instead of a `not ok # todo`).

    This function is useful for testing things that probably don't work the
    way they should but are reluctantly tolerated and if they do start working
    better no fuss should be made about the test suddenly passing.

    It's a nice way to document those "yes, we still have this ugly thing here
    that we wish we didn't" behaviors.  It can also be used to distinguish
    "tier 1" supported platforms (those which pass all tests even when
    `TESTLIB_NO_TOLERATE=1` is set) and "tier 2" supported platforms (those
    that pass all tests as long as `TESTLIB_NO_TOLERATE` is _not_ set).  (Tier
    3 would be those platforms that always fail at least one test.)

- test_external [<prereqs>] <desc> <cmd> <arg>

    Behaves just like `test_expect_success` with a script of "<cmd> <arg>"
    (assuming <cmd> and <arg> are first suitably quoted) except that stdout is
    always left on stdout even without `--verbose`.

    Use "eval" for <cmd> and pass a script as <arg> to use as a substitute
    `test_expect_success` that does not redirect stdout or to escape the
    two argument restriction.

- test_external_without_stderr [<prereqs>] <desc> <cmd> <arg>

    *IMPORTANT*: This function outputs _two_ test result lines!

    If using the `test_plan` function then each `test_external_without_stderr`
    function call counts as *TWO* planned tests!

    It works just like `test_external` (in fact, it calls test_external first)
    and then it performs a second subtest to see if _anything_ was output to
    stderr by "<cmd> <arg>" in which case the second subtest fails otherwise
    it succeeds.  If the `test_external` first subtest ends up being skipped
    then nothing will be output to stderr and the second subtest will always
    succeed (it will not be skipped).  In other words, the second subtest
    result line is always a plain "ok" or "not ok" and never has any "# skip"
    or "# todo" added to it even when the first subtest result line does.

    Note that the special prerequiste `LASTOK` behaves as expected here --
    that is if the first `test_external` call is skipped then its state
    _does NOT change_ regardless of the outcome of the second "stderr"
    subtest check.  In addition, if the `test_external` test is _not_
    skipped then the `LASTOK` prerequisite is guaranteed to only be true
    provided _both_ the `test_external` call suceeds _and_ no "stderr" output
    is generated.  In other words, it just does the right thing here so don't
    worry about it and go ahead and use it.


Standard Test Prerequisites
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The test result functions all take an optional first argument which is a comma
and/or whitespace separated list of positive or negative (prefixed with `!`)
prerequisites for the test to be run.  *All* of the listed prerequisites for
each test _must_ be satisfied or it will be skipped.

Additional prerequisites may be set using the `test_set_prereq` function but
there are a number of pre-defined prerequisites that may be tested:

- `AUTOIDENT`

    The `git var GIT_AUTHOR_IDENT` command succeeds when both `GIT_AUTHOR_NAME`
    and `GIT_AUTHOR_EMAIL` are unset.

- `BSLASHPSPEC`

    The backslash character (`\`) is allowed in path/file names.  Normally
    defined _except_ for `MINGW` and `CYGWIN`.

- `CASE_INSENSITIVE_FS`

    File names are case-insensitive (i.e. "foo" and "Foo" refer to the same
    file).

- `CMDLINE_LIMIT`

    Whether or not the `run_with_limited_cmdline` function appears to work
    (it does `ulimit -s 128` in a subshell and runs the command assuming that
    will limit the size of the command line argument list).

- `COLUMNS_CAN_BE_1`

    Set when the shell's `$COLUMNS` variable can be successfully set to 1.

- `CYGWIN`

    The CygWin environment is active.

- `EXECKEEPSPID`

    The process ID before and immediately after an `exec` call stays the
    same.  Normally defined for all but `MINGW`.

- `EXPENSIVE`

    The `TESTLIB_TEST_LONG` variable is non-empty (see the `--long-tests` aka
    `--expensive` test option).

- `FILEMODE`

    True if Git thinks the executable bit is supported properly (i.e.
    Git's `core.filemode` is set to true after `git_init`).

- `GITSHA1`

    This prerequisite is never cached.  It evaluates to true if the current
    value of the `test_hash_algo` variable is `sha1`.

- `GITSHA256`

    True if the Git executable being used to run the tests is at least version
    2.29.0.  If true it means `git init --object-format=sha256` can be used.
    (As well as `git init --object-format=sha1` if necessary.)

- `GREP_STRIPS_CR`

    The grep command strips off CR.  Normally only defined for `MINGW` and
    `CYGWIN`.

- `LASTOK`

    This is a special prerequisite that always succeeds for the first subtest
    in a test script and for every subtest thereafter for which the most
    immediately preceeding non-skipped test was "ok" (regardless of the
    presence any "# TODO").

    In other words, this can be used to skip a subtest if the preceeding
    subtest did not succeed.  Since "skipped" tests do not change the state
    of this prerequisite a single failure can cause a long chain of following
    subtests that use this prerequisite to be skipped.

- `MINGW`

    The MinGW environment is active.

- `NATIVE_CRLF`

    The native environment uses CR+LF line endings (normally only defined
    for `MINGW`).

- `NOT_ROOT`

    The `id -u` command succeeded and returned a non-0 value.

- `UTF8_NFD_TO_NFC`

    The file system automatically converts NFD unicode to NFC unicode.

- `PIPE`

    The `mkfifo` command is supported and works.

- `POSIXPERM`

    Sane, POSIX-style permissions.  *Not* normally defined for `MINGW`.

- `SANITY`

    File permission bits are honored (i.e. after doing `chmod a-r file` then
    a subsequent `cat file` will fail).  When running as root these "sanity"
    tests often fail.

- `SED_STRIPS_CR`

    The sed command strips off CR.  Normally only defined for `MINGW` and
    `CYGWIN`.

- `SYMLINKS`

    Symbolic links created using `ln -s` work.

- `USR_BIN_TIME`

    The result of `test -x /usr/bin/time` is true.


-----------------
Utility Functions
-----------------

These are convenience functions and while most of them are provided to be
called from the body of a script passed to one of the test_expect_...
functions, several of them can also be used from the main body of a test
script (`say`, `say_color`, `test_debug` and `test_pause` being prime examples
of such).

These functions are intended to be called only _after_ the `./test-lib.sh`
script has been sourced.  See the `README-TESTLIB-TG` file for additional
available utility functions that are TopGit-specific.

- die <optional> <message> <here>

    Can be used to exit a test script on an unexpected error, should be used
    after a `||` to preserve the exit code as in:

        perform_some_function perhaps with arguments || die

    If the <optional> <message> <here> is present, it will be included in the
    fatal error message (along with the exit code).

- error <msg> <goes> <here>

    Cause an instant test `Bail out!` error (including <msg> <goes> <here>).

    The original Git version of this function just did an exit after showing
    the error without using `Bail out!`, but these errors are terminal and the
    entire test suite should be stopped if one occurs and that is what will now
    happen when this function is called.

- git_init [<arg>...]

    Runs `git -c init.defaultBranch=master init "$@"`.  This is a convenience
    function that provides reproducibility in the face of changing Git defaults
    in the future.  Replace any "git init" calls with "git_init" in tests that
    depend on the name of the initial branch being "master" to avoid future
    breakage.

    When running Git version 2.29.0 or later, the
    `--object-format=$test_hash_algo` option will also be passed to `git init`
    immediately preceding the `"$@"` arguments.  Note that to override the
    automatically passed `--object-format=$test_hash_algo` option, simply
    provide another `--object-format=<hash>` option.  As far as `git init` is
    concerned, the last `--object-format=<hash>` option wins.

- list_contains <commalist> <pattern>

    Returns true if comma separated list <commalist> contains any item that
    matches the filename matching wildcard <pattern>.

    A shortcut for those uncomfortable with the `case` statement.

- sane_unset <varname>...

    An alias for `unset <varname>... || :` to workaround non-conforming shells
    that return a non-zero status if any of the variables were not already set.

- say <msg> <goes> <here>

    A convenient shortcut for `say_color info <msg> <goes> <here>`

- say_tap <msg> <goes> <here>

    A convenient shortcut for `say_color_tap info <msg> <goes> <here>`

- say_color <color> <msg> <goes> <here>

    Possible <color> values are:

      * "" (the empty string)  
        plain text with no color, suppressed when `--quiet` in effect
      * `error`  
        used for testing failures, typically shown in red
      * `skip`  
        used for test skip messages, typically shown in a light color
      * `warn`  
        warnings are shown in this, typically yellow (or brown)
      * `pass`  
        used when a complete test script passes, usually green
      * `info`  
        info messages and non-harness TAP messages, usually a light color
      * `reset`  
        turns off color, used internally, should not be used by callers

    Using anything else for <color> ends up outputting plain text followed by
    the color reset code.

    If `--quiet` is in effect, anything output using `""` (the empty string)
    as the color name will be supressed entirely.

    If `--no-color` is in effect (perhaps implicitly) the color code sequences
    are omitted from the output.

    If `$HARNESS_ACTIVE` and the first character of <msg> is `#` then that
    single character is always output _without_ any preceding color codes (the
    first character to be in color will be the following one unless, of course,
    the color name is `""` or `--no-color` is in effect).

- say_color_tap <color> <msg> <goes> <here>

    When `$HARNESS_ACTIVE` this always outputs "<msg> <goes> <here>" _without_
    any color sequences regardless of the presence of the `--quiet` option.

    If there is no `$HARNESS_ACTIVE` then this call is identical to `say_color`
    with the exact same arguments.

- test_asv <id>

    Output the value of the hash algorithm specific value cached with the
    id <id> to standard output.  This will typically be used as
    `"$(test_asv <id>)"`.  The test_v_asv function does not cause a subshell to
    be created and is therefore recommended since it's more efficient.

    A fatal error will occur if no value has been set for <id> using the
    `test_asv_cache` function.

    See further details in the description for `test_asv_cache`.

- test_asv_cache <database>

    Read each line of <database> using the shell's `read` function into three
    variables.  The first is the <id> to be used with `test_asv` and
    `test_v_asv`, the second is either `sha1` or `sha256` and the rest of the
    line is the algorithm specific value to associate with that database entry.

    Blank lines and lines with the first non-space character a `#` are ignored.

    If the <database> is given as a single hyphen (-) then the database lines
    will be read from standard input.

    For example:

        test_asv_cache '
            # this is a comment
            01 sha1   value for sha1
            01 sha256 \
            value for sha256

               # this is a comment too

            v33 sha1   hash is sha1
            v33 sha256 hash is sha256
        '

    The value of <id> must be a valid shell variable name after having a letter
    prefix added.  In other words, if <id> is "5" then prefixing a letter such
    as "z" produces "z5" which is a valid shell variable name.  In general,
    the <id> must consist of only alphanumeric characters plus underscore (`_`).

    In the case of duplicate <id> plus hash keys, the last one wins.

    Note that since the shell's read function is used with the standard setting
    for `$IFS` extra whitespace may be used around the <id> and hash name and
    the value will have whitespace trimmed from its beginning and end.  In
    addition, since the shell's read function supports line continuation with
    a backslash (`\`) as the last character on a line, the value for each entry
    may be split across lines using that feature if desired.

    The `test_asv_cache` function may be invoked more than once.  Subsequent
    invocations add to the cache (replacing any items with the same <id> plus
    hash key).  Since each individual test runs in its own subshell (unless
    `TESTLIB_TEST_NO_SUBSHELL` has been used), the effects of calls to
    `test_asv_cache` from inside an individual test will not persist after that
    test has completed (successfully or not).

    Providing a hash name of other than `sha1` or `sha256` will produce a
    fatal error.  Note that it is *not* an error to provide a database with
    `sha256` entries even when running a version of Git prior to 2.29.0 -- they
    will just never be produced by `test_asv` or `test_v_asv` in that case.

    After executing the above example, the following code can be used:

        test_asv 01  # outputs "value for sha1" or "value for sha256"
        test_asv v33 # outputs "hash is sha1" or "hash is sha256"
        test_v_asv ex1 01  # sets variable `ex1` to "value for sha1"
                           # or "value for sha256"
        test_v_asv ex2 v33 # sets variable `ex2` to "hash is sha1"
                           # or "hash is sha256"

    Which value is chosen by `test_asv` or `test_v_asv` depends solely on the
    current value of `test_hash_algo` at the time `test_asv` or `test_v_asv`
    is executed.

- test_at_end_hook_

    This function is called by `test_done` if there are no unexpected failures.
    By default it's defined to be just `:` but should be re-defined by each
    test script file as needed.  Note that it _will_ be called when the entire
    test script is skipped with a `1..0` plan line.

- test_clear_when_finished

    Any `test_when_finished` items already scheduled in the subtest script
    so far are cleared (i.e. removed).  Calling `test_clear_when_finished`
    before `test_when_finished` has first been called silently does nothing
    with no error.

- test_cmp <arg>...

    Shortcut for:

        $TESTLIB_TEST_CMP <arg>...

    Useful because `diff -u` will be used where supported instead of `cmp`.
    See also `test_diff` for an alternative.

- test_cmp_bin <arg>...

    Shortcut for:

        cmp <arg>...

    There's no real compelling reason to use this other than to look nice
    next to `test_cmp`.

- test_cmp_rev <expect-rev> <actual-rev>

    Save output of `git rev-parse --verify` on each argument to a file and
    then run `test_cmp expect.rev actual.rev` on the resulting two files.

    The temporary files are actually placed in TRASHTMP_DIRECTORY so there's
    no need to be concerned about contaminating a working tree that's being
    used for testing or needing to do a `cd` to avoid that.

- test_commit [--notick] [--signoff] <message> [<file> [<contents> [<tag>]]]

    Create a new Git commit with "<message>" as the commit message optionally
    having a signed-off-by line (`--signoff`) using the next tick time by
    calling `test_tick` (unless `--notick` is used).

    <file> defaults to "<message>.t", <contents> and <tag> default to
    "<message>".

    The "<contents>" will be written (using `printf '%s\n'`) to <file> which is
    then added and committed using <message> and then tagged using <message>.

    It will not be tagged if <tag> is the empty string or contains any
    whitespace or invalid ref name characters.  (Including at least one '^' or
    '~' is a simple way to keep a single "word" that's a valid filename while
    at the same time suppressing creation of a tag while not needing to
    supply anything other than the <message> argument.)

- test_config [-C <dir>] <name> <value> [...]

    Run `git [-C <dir>] config <name> <value> [...]` now and schedule a
    `git [-C <dir>] config --unset-all <name>` (via `test_unconfig`) using
    `test_when_finished`.

    This function allows for easy temporary configuration changes that are
    automatically undone when the current test finishes.

- test_config_global <name> <value> [...]

    Run `git config --global <name> <value> [...]` now and schedule a
    `git [-C <dir>] config --unset-all --global <name>` (via `test_unconfig`)
    using `test_when_finished`.

    This function allows for easy temporary global configuration changes that
    are automatically undone when the current test finishes.

- test_copy_bytes <count>

    This is a shortcut for a call to the `dd` utility (unlike the Git version
    which uses perl) to transfer <count> bytes (or up to EOF) from stdin to
    stdout.

- test_create_repo <path>

    Shortcut for:

        (mkdir -p "<path>" && cd "<path>" && git_init)

    Except that an empty template directory is used and if that doesn't succeed
    in suppressing creation of a hooks directory the hooks directory will be
    renamed to `hooks-disabled`.

    Note that since Git will happily reinitialize an existing Git repository
    this command can succeed on a pre-existing repository without altering its
    contents.

- test_debug [<cmd> [<arg>...]]

    This function does nothing (it's a fancy comment) _unless_ `--debug` is
    used in which case <cmd> [<arg>...] is executed with standard output and
    standard error redirected to the original standard error of the test
    script (in other words, you don't need to add `--verbose` to see the
    output when `--debug` is active).

    Note that this is different than the original Git version that only takes
    a single argument and "eval"s it (while not guaranteeing anything about
    where the output goes).  To get the Git "eval" equivalent, use `eval` as
    the first <arg> and the string to be "eval"'d as the second.

- test_diff <arg>...

    Shortcut for:

        git --no-pager -c core.abbrev=16 diff --no-color --exit-code \
          --no-prefix --no-index <arg>...

    Always gives nice diffs and they're always `-u` diffs.
    This should be usable as a drop-in replacement for `test_cmp` everywhere
    and its output should be deterministic as no dates or times are included.

- test_dir_is_empty <dirpath>

    Fail verbosely (with directory contents) unless <dirpath> is an existing
    and empty (only `.` and `..` entries) directory.

- test_env [VAR=VAL]... <cmd> <arg>...

    In a subshell set and export each `VAR=VAL` and then run `<cmd> <arg>...`.

    Obviously, since it's a subshell no variable changes will persist, but this
    makes it easy to temporarily change a variable while running some shell
    function.

- test_expect_code <status> <cmd> [<arg>...]

    Runs `<cmd> <arg>...` and fails verbosely unless the resulting status code
    is <status>.

- test_get_temp [-d] [<name>]

    Create a new temporary file (or directory with -d) in the temporary
    directory $TRASHTMP_DIRECTORY with optional pattern prefix "<name>." and
    output the resulting unique name of the newly created empty file (or
    directory with -d).

    The $TRASHTMP_DIRECTORY is created on-demand the first time this function
    is called and is guaranteed to be outside of $TRASH_DIRECTORY but still
    unique to the test script currently being run.

- test_have_prereq <PREREQ>...

    Test a list of zero or more whitespace and/or comma separated prereqs
    (the same as can be given to any of the test result functions).  As with
    the test result functions, prefixing a prerequisite with a single `!`
    requires that it _not_ be present.  Result code is 0 if the requirements
    are satisfied, non-zero if not.

- test_line_count <op> <val> <file>

    Verbosely fails if `test $(( $(wc -l < "<file>") )) "<op>" "<val>"` fails.

- test_match_signal <signum> <exitcode>

    Returns true if <exitcode> represents an exit from signal <signum> (which
    must be numeric).  This function only exists to accomodate `ksh` which
    uses 256+<signum> instead of the POSIX 128+<signum> for signal exit codes.

- test_merge <message> [<opt>...] <commit>

    Shortcut for:

        test_tick && git merge -m "$@" && git tag "<message>"

    Except that `--allow-unrelated-histories` is automatically supplied for
    Git 2.9 or later and the tag is skipped if "<message>" is not tagish.

- test_might_fail <cmd> [<arg>...]

    Just a shortcut for `test_must_fail ok=success <cmd> <arg>...`.

    This is useful when it's okay for <cmd> to succeed or for it to fail
    provided the failure is a "normal" (i.e. non-signal) failure.

- test_must_be_empty <file>

    Verbosely complain (and fail) showing <file>'s contents if it's not empty
    (i.e. -s <file> succeeds).

- test_must_fail [ok=<commalist>] <cmd> [<arg>...]

    Runs `<cmd> <arg>...` and verbosely converts all result codes into either
    0 or 1 where "normal" failures become 0 and others become 1.

    This function should be used when a failure is required but only if the
    failure is *not* the result of a signal, command not found or command not
    executable error.

    If <commalist> contains "success" then a result code of 0 is _not_
    converted to 1 (it stays 0).  If <commalist> contains "sigpipe" then an
    exit due to `SIGPIPE` is converted to status 0 (otherwise it becomes 1).

- test_path_is_dir <path> [<msg>]

    Fail verbosely (including <msg> if given) if `test -d <path>` fails.

- test_path_is_file <path> [<msg>]

    Fail verbosely (including <msg> if given) if `test -f <path>` fails.

- test_path_is_missing <path> [<msg>...]

    Fail verbosely (including <msg>... if given) if `test -e <path>` _succeeds_.

- test_pause

    Spawn an interactive `$SHELL` to pause testing until it exits -- causes an
    error if used without `--verbose`.  Should be used for debugging only.

    Something like this can be used to leave it in a script (although this is
    not recommended):

        test_debug eval "want_no_verbose || test_pause"

    which will cause the test in question to spawn a subshell whenever it's run
    with both the --verbose and --debug options.

- test_seq [<start>] <end>

    <start> defaults to 1.

    Output each of the numbers from <start> to <end> inclusive (incrementing by
    1) each followed by a newline to stdout.  If <end> is less than <start>
    nothing is output.

- test_set_editor <path-to-editor>

    Set and export the `EDITOR` environment variable but using tricks so that
    <path-to-editor> is allowed to contain any value (including spaces, quotes,
    etc.) without needing any special quoting.

- test_set_hash_algo <algorithm>

    The value of <algorithm> must be either `sha1` or `sha256`.  Attempting to
    set a value of `sha256` with a version of Git prior to version 2.29.0 will
    cause a fatal error.  The value of both the `GIT_DEFAULT_HASH` environment
    variable and the `test_hash_algo` variable are set by this function.  The
    `TESTLIB_GIT_DEFAULT_HASH` environment variable is, however, left untouched.

    An implicit `test_set_hash_algo ${TESTLIB_GIT_DEFAULT_HASH:-sha1}` happens
    early during test setup.

- test_set_prereq <PREREQ>

    Indicate that the test prerequisite <PREREQ> is available (should be a
    single word in ALL CAPS).  It may then be used as a prereq for any of the
    test result functions or be explicitly tested with `test_have_prereq`.

    Note that for this to work inside a subtest and have the result be
    available to subsequent subtests, it needs to be preceded by
    `test_when_finished` (and also be run without that if `test_have_prereq` is
    intended to work subsequently *inside* the same subtest's subshell).

- test_skip_or_die <mode> <msg>

    Don't use this function, it's confusing, use either `test_plan 0` or
    `error` directly.

    If <mode> is `auto` it's the same as `test_plan 0 <msg>`.

    If <mode> is `true` it's the same as `error <msg>`.

    If <mode> is anything else it's a more verbose call to `error`.

- test_tick

    Set and export `GIT_COMMITTER_DATE` and `GIT_AUTHOR_DATE` to the same
    value (initially 1112911993 -- the time of the first Git commit) increasing
    it by exactly 60 seconds each time `test_tick` is called.

    Note that when a test script starts running neither `GIT_COMMITTER_DATE`
    nor `GIT_AUTHOR_DATE` are initially set.  It's not until after the first
    time `test_tick` is called (it's called implicitly by `test_commit` and
    `tg_test_create_branch` unless they're given the `--notick` option) that
    both of them are set (unless the test script otherwise sets them itself).

    See also the description of the `test_tick` variable above.

- test_tristate <varname>

    Examines contents of `$<varname>` and sets `$<varname>` to one of `false`
    `true` or `auto`.  An unset variable becomes `auto` and an empty string
    variable becomes `false` otherwise there should be no surprises except
    that anything that is not a Git boolean or `auto` is treated as `true`.

    The original version from the Git test library uses Git itself to do this
    conversion, but this implementation is strictly shell built-ins.

- test_unconfig [-C <dir>] <arg>...

    Runs `git [-C <dir>] config --unset-all <arg>...` immediately but ignores
    any error resulting from the value(s) to be unset not actually being
    currently set at all (status 5).

    Can be used for global values simply by making the first <arg> be `--global`
    and the rest the global arg(s) to unset.

- test_v_asv <varname> <id>

    Set <varname> to the value of the hash algorithm specific value cached with
    the id <id>.

    A fatal error will occur if no value has been set for <id> using the
    `test_asv_cache` function.

    See further details in the description for `test_asv_cache`.

- test_v_git_mt <varname> <object-type> [<hash>]

    With an <object-type> of `blob`, `tree` or 'null`, set <varname> to the
    correct $test_hash_algo hash algorithm value for an empty Git
    <object-type> object.  (A `null` <object-type> returns a string of 0's of
    the proper length for $test_hash_algo.)

    If <hash> is provided, it must be `sha1` or `sha256` or a fatal error will
    occur.  If <hash> is non-empty it will be used as the hash algorithm
    instead of $test_hash_algo.

    An unknown <object-type> will produce a fatal error.

- test_when_finished <cmd> [<arg>...]

    This function only works inside a test script!

    Causes <cmd> [<arg>...] to be run when the current test script (the
    <script> arg to a test result function) exits.  May be used more than
    once to schedule multiple items.

    This function differs from Git's version in that <cmd> [<arg>...]
    are automagically quoted and stored in a "test_when_finished_<n>.sh"
    script that then gets sourced outside of any subshell that may have
    been created by the test script at test exit time.  (The "<n>" value
    is the number of the subtest within the test script and the script
    itself is stored in the TRASHTMP_DIRECTORY.)

    This means that `TESTLIB_TEST_NO_SUBSHELL` has no effect on this
    functionality nor do subshells created implicitly (or explicitly) by
    the test script itself.

    Git's version uses eval.  To get the same effect make the <cmd> be
    "eval".  However, that's not recommended as the eval will take place
    outside of any test script subshells which means none of the variables
    created inside the test script's subshells will be accessible at that time.
    Instead use the normal form (it's much simpler to use anyway) which causes
    any variables to be evaluated immediately when `test_when_finished` is
    called to schedule the "when finished" operation.

    This approach, however, precludes using `test_when_finished` to perform
    some action using a variable that has not yet been set.  In that case the
    "eval" form will be needed and probably `TESTLIB_TEST_NO_SUBSHELL` will
    also have to be set to true to make it work.

    See also `test_clear_when_finished`.

- test_write_lines <arg>...

    A lazy shortcut for:

        printf '%s\n' <arg>...

    Although since it's more characters to type perhaps it's not so lazy. ;)

- verbose <cmd> [<arg>...]

    Run `<cmd> <arg>...` and verbosely complain (showing command and args) if
    it fails, but the exit status on failure will be converted to 1.

- wc [-c|-m] [-lw] [<file>...]

    This is a wrapper around the wc utility.  Some systems produce formatted
    output with extra spaces in it that this wrapper conveniently removes.

    BEWARE!  The output from the system's native wc will have all leading and
    trailing spaces removed and all sequences of internal whitespace converted
    to a single space.

    Although it's not been disabled, avoid using wc with any <file> arguments!

    Parsing out the filenames from the result is error prone (and they will
    all end up on one line if there's more than one and any internal runs of
    whitespace in the name(s) will each be converted to a single space courtesy
    of the wrapper).

    Instead redirect standard input to the file or files to be counted and
    use `cat` if there's more than one file, something like this:

        lines_1=$(wc -l < file1)
        lines_2_plus_3=$(cat file2 file3 | wc -l)

    To test line counts in a test script, use something like this:

        printf "%s\n" one two three four >testfile &&
        lines=$(wc -l <testfile) &&
        test $lines -eq 4

    While the output of a command can be piped directly to wc that means
    the command's result status will be discarded (in favor of wc's if it's
    the last command in the pipeline) so that should generally be avoided
    (although the `cat` example above is probably okay to use).

    If you're using wc to count something on its standard input then you can
    safely use it just like the POSIX version without needing to be concerned
    about bogus whitespace showing up in the result which is the whole point
    of this wrapper in the first place.

- write_script <file> [<shell-path>] < <script-text>

    Write a shebang line using <shell-path> (default is `$SHELL_PATH`) to
    <file> and then append <script-text> to it and then finally add execute
    permission to the resulting <file>.

- yes [<expletive>]

    If <expletive> is omitted, `y` is used.

    Outputs "<expletive>" (and a trailing newline) 99 times.

    This is basically the same as the POSIX `yes` utility except that output
    is limited to 99 lines and it's implemented entirely as shell code.