about summary refs log tree commit diff
path: root/third_party/git/t/README
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/t/README')
-rw-r--r--third_party/git/t/README1182
1 files changed, 0 insertions, 1182 deletions
diff --git a/third_party/git/t/README b/third_party/git/t/README
deleted file mode 100644
index 2adaf7c2d274..000000000000
--- a/third_party/git/t/README
+++ /dev/null
@@ -1,1182 +0,0 @@
-Core Git Tests
-==============
-
-This directory holds many test scripts for core Git tools.  The
-first part of this short document describes how to run the tests
-and read their output.
-
-When fixing the tools or adding enhancements, you are strongly
-encouraged to add tests in this directory to cover what you are
-trying to fix or enhance.  The later part of this short document
-describes how your test scripts should be organized.
-
-
-Running Tests
--------------
-
-The easiest way to run tests is to say "make".  This runs all
-the tests.
-
-    *** t0000-basic.sh ***
-    ok 1 - .git/objects should be empty after git init in an empty repo.
-    ok 2 - .git/objects should have 3 subdirectories.
-    ok 3 - success is reported like this
-    ...
-    ok 43 - very long name in the index handled sanely
-    # fixed 1 known breakage(s)
-    # still have 1 known breakage(s)
-    # passed all remaining 42 test(s)
-    1..43
-    *** t0001-init.sh ***
-    ok 1 - plain
-    ok 2 - plain with GIT_WORK_TREE
-    ok 3 - plain bare
-
-Since the tests all output TAP (see http://testanything.org) they can
-be run with any TAP harness. Here's an example of parallel testing
-powered by a recent version of prove(1):
-
-    $ prove --timer --jobs 15 ./t[0-9]*.sh
-    [19:17:33] ./t0005-signals.sh ................................... ok       36 ms
-    [19:17:33] ./t0022-crlf-rename.sh ............................... ok       69 ms
-    [19:17:33] ./t0024-crlf-archive.sh .............................. ok      154 ms
-    [19:17:33] ./t0004-unwritable.sh ................................ ok      289 ms
-    [19:17:33] ./t0002-gitfile.sh ................................... ok      480 ms
-    ===(     102;0  25/?  6/?  5/?  16/?  1/?  4/?  2/?  1/?  3/?  1... )===
-
-prove and other harnesses come with a lot of useful options. The
---state option in particular is very useful:
-
-    # Repeat until no more failures
-    $ prove -j 15 --state=failed,save ./t[0-9]*.sh
-
-You can give DEFAULT_TEST_TARGET=prove on the make command (or define it
-in config.mak) to cause "make test" to run tests under prove.
-GIT_PROVE_OPTS can be used to pass additional options, e.g.
-
-    $ make DEFAULT_TEST_TARGET=prove GIT_PROVE_OPTS='--timer --jobs 16' test
-
-You can also run each test individually from command line, like this:
-
-    $ sh ./t3010-ls-files-killed-modified.sh
-    ok 1 - git update-index --add to add various paths.
-    ok 2 - git ls-files -k to show killed files.
-    ok 3 - validate git ls-files -k output.
-    ok 4 - git ls-files -m to show modified files.
-    ok 5 - validate git ls-files -m output.
-    # passed all 5 test(s)
-    1..5
-
-You can pass --verbose (or -v), --debug (or -d), and --immediate
-(or -i) command line argument to the test, or by setting GIT_TEST_OPTS
-appropriately before running "make". Short options can be bundled, i.e.
-'-d -v' is the same as '-dv'.
-
--v::
---verbose::
-	This makes the test more verbose.  Specifically, the
-	command being run and their output if any are also
-	output.
-
---verbose-only=<pattern>::
-	Like --verbose, but the effect is limited to tests with
-	numbers matching <pattern>.  The number matched against is
-	simply the running count of the test within the file.
-
--x::
-	Turn on shell tracing (i.e., `set -x`) during the tests
-	themselves. Implies `--verbose`.
-	Ignored in test scripts that set the variable 'test_untraceable'
-	to a non-empty value, unless it's run with a Bash version
-	supporting BASH_XTRACEFD, i.e. v4.1 or later.
-
--d::
---debug::
-	This may help the person who is developing a new test.
-	It causes the command defined with test_debug to run.
-	The "trash" directory (used to store all temporary data
-	during testing) is not deleted even if there are no
-	failed tests so that you can inspect its contents after
-	the test finished.
-
--i::
---immediate::
-	This causes the test to immediately exit upon the first
-	failed test. Cleanup commands requested with
-	test_when_finished are not executed if the test failed,
-	in order to keep the state for inspection by the tester
-	to diagnose the bug.
-
--l::
---long-tests::
-	This causes additional long-running tests to be run (where
-	available), for more exhaustive testing.
-
--r::
---run=<test-selector>::
-	Run only the subset of tests indicated by
-	<test-selector>.  See section "Skipping Tests" below for
-	<test-selector> syntax.
-
---valgrind=<tool>::
-	Execute all Git binaries under valgrind tool <tool> and exit
-	with status 126 on errors (just like regular tests, this will
-	only stop the test script when running under -i).
-
-	Since it makes no sense to run the tests with --valgrind and
-	not see any output, this option implies --verbose.  For
-	convenience, it also implies --tee.
-
-	<tool> defaults to 'memcheck', just like valgrind itself.
-	Other particularly useful choices include 'helgrind' and
-	'drd', but you may use any tool recognized by your valgrind
-	installation.
-
-	As a special case, <tool> can be 'memcheck-fast', which uses
-	memcheck but disables --track-origins.  Use this if you are
-	running tests in bulk, to see if there are _any_ memory
-	issues.
-
-	Note that memcheck is run with the option --leak-check=no,
-	as the git process is short-lived and some errors are not
-	interesting. In order to run a single command under the same
-	conditions manually, you should set GIT_VALGRIND to point to
-	the 't/valgrind/' directory and use the commands under
-	't/valgrind/bin/'.
-
---valgrind-only=<pattern>::
-	Like --valgrind, but the effect is limited to tests with
-	numbers matching <pattern>.  The number matched against is
-	simply the running count of the test within the file.
-
---tee::
-	In addition to printing the test output to the terminal,
-	write it to files named 't/test-results/$TEST_NAME.out'.
-	As the names depend on the tests' file names, it is safe to
-	run the tests with this option in parallel.
-
--V::
---verbose-log::
-	Write verbose output to the same logfile as `--tee`, but do
-	_not_ write it to stdout. Unlike `--tee --verbose`, this option
-	is safe to use when stdout is being consumed by a TAP parser
-	like `prove`. Implies `--tee` and `--verbose`.
-
---with-dashes::
-	By default tests are run without dashed forms of
-	commands (like git-commit) in the PATH (it only uses
-	wrappers from ../bin-wrappers).  Use this option to include
-	the build directory (..) in the PATH, which contains all
-	the dashed forms of commands.  This option is currently
-	implied by other options like --valgrind and
-	GIT_TEST_INSTALLED.
-
---no-bin-wrappers::
-	By default, the test suite uses the wrappers in
-	`../bin-wrappers/` to execute `git` and friends. With this option,
-	`../git` and friends are run directly. This is not recommended
-	in general, as the wrappers contain safeguards to ensure that no
-	files from an installed Git are used, but can speed up test runs
-	especially on platforms where running shell scripts is expensive
-	(most notably, Windows).
-
---root=<directory>::
-	Create "trash" directories used to store all temporary data during
-	testing under <directory>, instead of the t/ directory.
-	Using this option with a RAM-based filesystem (such as tmpfs)
-	can massively speed up the test suite.
-
---chain-lint::
---no-chain-lint::
-	If --chain-lint is enabled, the test harness will check each
-	test to make sure that it properly "&&-chains" all commands (so
-	that a failure in the middle does not go unnoticed by the final
-	exit code of the test). This check is performed in addition to
-	running the tests themselves. You may also enable or disable
-	this feature by setting the GIT_TEST_CHAIN_LINT environment
-	variable to "1" or "0", respectively.
-
---stress::
-	Run the test script repeatedly in multiple parallel jobs until
-	one of them fails.  Useful for reproducing rare failures in
-	flaky tests.  The number of parallel jobs is, in order of
-	precedence: the value of the GIT_TEST_STRESS_LOAD
-	environment variable, or twice the number of available
-	processors (as shown by the 'getconf' utility),	or 8.
-	Implies `--verbose -x --immediate` to get the most information
-	about the failure.  Note that the verbose output of each test
-	job is saved to 't/test-results/$TEST_NAME.stress-<nr>.out',
-	and only the output of the failed test job is shown on the
-	terminal.  The names of the trash directories get a
-	'.stress-<nr>' suffix, and the trash directory of the failed
-	test job is renamed to end with a '.stress-failed' suffix.
-
---stress-jobs=<N>::
-	Override the number of parallel jobs. Implies `--stress`.
-
---stress-limit=<N>::
-	When combined with --stress run the test script repeatedly
-	this many times in each of the parallel jobs or until one of
-	them fails, whichever comes first. Implies `--stress`.
-
-You can also set the GIT_TEST_INSTALLED environment variable to
-the bindir of an existing git installation to test that installation.
-You still need to have built this git sandbox, from which various
-test-* support programs, templates, and perl libraries are used.
-If your installed git is incomplete, it will silently test parts of
-your built version instead.
-
-When using GIT_TEST_INSTALLED, you can also set GIT_TEST_EXEC_PATH to
-override the location of the dashed-form subcommands (what
-GIT_EXEC_PATH would be used for during normal operation).
-GIT_TEST_EXEC_PATH defaults to `$GIT_TEST_INSTALLED/git --exec-path`.
-
-
-Skipping Tests
---------------
-
-In some environments, certain tests have no way of succeeding
-due to platform limitation, such as lack of 'unzip' program, or
-filesystem that do not allow arbitrary sequence of non-NUL bytes
-as pathnames.
-
-You should be able to say something like
-
-    $ GIT_SKIP_TESTS=t9200.8 sh ./t9200-git-cvsexport-commit.sh
-
-and even:
-
-    $ GIT_SKIP_TESTS='t[0-4]??? t91?? t9200.8' make
-
-to omit such tests.  The value of the environment variable is a
-SP separated list of patterns that tells which tests to skip,
-and either can match the "t[0-9]{4}" part to skip the whole
-test, or t[0-9]{4} followed by ".$number" to say which
-particular test to skip.
-
-For an individual test suite --run could be used to specify that
-only some tests should be run or that some tests should be
-excluded from a run.
-
-The argument for --run is a list of individual test numbers or
-ranges with an optional negation prefix that define what tests in
-a test suite to include in the run.  A range is two numbers
-separated with a dash and matches a range of tests with both ends
-been included.  You may omit the first or the second number to
-mean "from the first test" or "up to the very last test"
-respectively.
-
-Optional prefix of '!' means that the test or a range of tests
-should be excluded from the run.
-
-If --run starts with an unprefixed number or range the initial
-set of tests to run is empty. If the first item starts with '!'
-all the tests are added to the initial set.  After initial set is
-determined every test number or range is added or excluded from
-the set one by one, from left to right.
-
-Individual numbers or ranges could be separated either by a space
-or a comma.
-
-For example, to run only tests up to a specific test (21), one
-could do this:
-
-    $ sh ./t9200-git-cvsexport-commit.sh --run='1-21'
-
-or this:
-
-    $ sh ./t9200-git-cvsexport-commit.sh --run='-21'
-
-Common case is to run several setup tests (1, 2, 3) and then a
-specific test (21) that relies on that setup:
-
-    $ sh ./t9200-git-cvsexport-commit.sh --run='1 2 3 21'
-
-or:
-
-    $ sh ./t9200-git-cvsexport-commit.sh --run=1,2,3,21
-
-or:
-
-    $ sh ./t9200-git-cvsexport-commit.sh --run='-3 21'
-
-As noted above, the test set is built by going through the items
-from left to right, so this:
-
-    $ sh ./t9200-git-cvsexport-commit.sh --run='1-4 !3'
-
-will run tests 1, 2, and 4.  Items that come later have higher
-precedence.  It means that this:
-
-    $ sh ./t9200-git-cvsexport-commit.sh --run='!3 1-4'
-
-would just run tests from 1 to 4, including 3.
-
-You may use negation with ranges.  The following will run all
-test in the test suite except from 7 up to 11:
-
-    $ sh ./t9200-git-cvsexport-commit.sh --run='!7-11'
-
-Some tests in a test suite rely on the previous tests performing
-certain actions, specifically some tests are designated as
-"setup" test, so you cannot _arbitrarily_ disable one test and
-expect the rest to function correctly.
-
---run is mostly useful when you want to focus on a specific test
-and know what setup is needed for it.  Or when you want to run
-everything up to a certain test.
-
-
-Running tests with special setups
----------------------------------
-
-The whole test suite could be run to test some special features
-that cannot be easily covered by a few specific test cases. These
-could be enabled by running the test suite with correct GIT_TEST_
-environment set.
-
-GIT_TEST_FAIL_PREREQS=<boolean> fails all prerequisites. This is
-useful for discovering issues with the tests where say a later test
-implicitly depends on an optional earlier test.
-
-There's a "FAIL_PREREQS" prerequisite that can be used to test for
-whether this mode is active, and e.g. skip some tests that are hard to
-refactor to deal with it. The "SYMLINKS" prerequisite is currently
-excluded as so much relies on it, but this might change in the future.
-
-GIT_TEST_GETTEXT_POISON=<boolean> turns all strings marked for
-translation into gibberish if true. Used for spotting those tests that
-need to be marked with a C_LOCALE_OUTPUT prerequisite when adding more
-strings for translation. See "Testing marked strings" in po/README for
-details.
-
-GIT_TEST_SPLIT_INDEX=<boolean> forces split-index mode on the whole
-test suite. Accept any boolean values that are accepted by git-config.
-
-GIT_TEST_PROTOCOL_VERSION=<n>, when set, makes 'protocol.version'
-default to n.
-
-GIT_TEST_FULL_IN_PACK_ARRAY=<boolean> exercises the uncommon
-pack-objects code path where there are more than 1024 packs even if
-the actual number of packs in repository is below this limit. Accept
-any boolean values that are accepted by git-config.
-
-GIT_TEST_OE_SIZE=<n> exercises the uncommon pack-objects code path
-where we do not cache object size in memory and read it from existing
-packs on demand. This normally only happens when the object size is
-over 2GB. This variable forces the code path on any object larger than
-<n> bytes.
-
-GIT_TEST_OE_DELTA_SIZE=<n> exercises the uncommon pack-objects code
-path where deltas larger than this limit require extra memory
-allocation for bookkeeping.
-
-GIT_TEST_VALIDATE_INDEX_CACHE_ENTRIES=<boolean> checks that cache-tree
-records are valid when the index is written out or after a merge. This
-is mostly to catch missing invalidation. Default is true.
-
-GIT_TEST_COMMIT_GRAPH=<boolean>, when true, forces the commit-graph to
-be written after every 'git commit' command, and overrides the
-'core.commitGraph' setting to true.
-
-GIT_TEST_COMMIT_GRAPH_CHANGED_PATHS=<boolean>, when true, forces
-commit-graph write to compute and write changed path Bloom filters for
-every 'git commit-graph write', as if the `--changed-paths` option was
-passed in.
-
-GIT_TEST_FSMONITOR=$PWD/t7519/fsmonitor-all exercises the fsmonitor
-code path for utilizing a file system monitor to speed up detecting
-new or changed files.
-
-GIT_TEST_INDEX_VERSION=<n> exercises the index read/write code path
-for the index version specified.  Can be set to any valid version
-(currently 2, 3, or 4).
-
-GIT_TEST_PACK_SPARSE=<boolean> if disabled will default the pack-objects
-builtin to use the non-sparse object walk. This can still be overridden by
-the --sparse command-line argument.
-
-GIT_TEST_PRELOAD_INDEX=<boolean> exercises the preload-index code path
-by overriding the minimum number of cache entries required per thread.
-
-GIT_TEST_ADD_I_USE_BUILTIN=<boolean>, when true, enables the
-built-in version of git add -i. See 'add.interactive.useBuiltin' in
-git-config(1).
-
-GIT_TEST_INDEX_THREADS=<n> enables exercising the multi-threaded loading
-of the index for the whole test suite by bypassing the default number of
-cache entries and thread minimums. Setting this to 1 will make the
-index loading single threaded.
-
-GIT_TEST_MULTI_PACK_INDEX=<boolean>, when true, forces the multi-pack-
-index to be written after every 'git repack' command, and overrides the
-'core.multiPackIndex' setting to true.
-
-GIT_TEST_SIDEBAND_ALL=<boolean>, when true, overrides the
-'uploadpack.allowSidebandAll' setting to true, and when false, forces
-fetch-pack to not request sideband-all (even if the server advertises
-sideband-all).
-
-GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=<boolean>, when true (which is
-the default when running tests), errors out when an abbreviated option
-is used.
-
-GIT_TEST_DEFAULT_HASH=<hash-algo> specifies which hash algorithm to
-use in the test scripts. Recognized values for <hash-algo> are "sha1"
-and "sha256".
-
-Naming Tests
-------------
-
-The test files are named as:
-
-	tNNNN-commandname-details.sh
-
-where N is a decimal digit.
-
-First digit tells the family:
-
-	0 - the absolute basics and global stuff
-	1 - the basic commands concerning database
-	2 - the basic commands concerning the working tree
-	3 - the other basic commands (e.g. ls-files)
-	4 - the diff commands
-	5 - the pull and exporting commands
-	6 - the revision tree commands (even e.g. merge-base)
-	7 - the porcelainish commands concerning the working tree
-	8 - the porcelainish commands concerning forensics
-	9 - the git tools
-
-Second digit tells the particular command we are testing.
-
-Third digit (optionally) tells the particular switch or group of switches
-we are testing.
-
-If you create files under t/ directory (i.e. here) that is not
-the top-level test script, never name the file to match the above
-pattern.  The Makefile here considers all such files as the
-top-level test script and tries to run all of them.  Care is
-especially needed if you are creating a common test library
-file, similar to test-lib.sh, because such a library file may
-not be suitable for standalone execution.
-
-
-Writing Tests
--------------
-
-The test script is written as a shell script.  It should start
-with the standard "#!/bin/sh", and an
-assignment to variable 'test_description', like this:
-
-	#!/bin/sh
-
-	test_description='xxx test (option --frotz)
-
-	This test registers the following structure in the cache
-	and tries to run git-ls-files with option --frotz.'
-
-
-Source 'test-lib.sh'
---------------------
-
-After assigning test_description, the test script should source
-test-lib.sh like this:
-
-	. ./test-lib.sh
-
-This test harness library does the following things:
-
- - If the script is invoked with command line argument --help
-   (or -h), it shows the test_description and exits.
-
- - Creates an empty test directory with an empty .git/objects database
-   and chdir(2) into it.  This directory is 't/trash
-   directory.$test_name_without_dotsh', with t/ subject to change by
-   the --root option documented above, and a '.stress-<N>' suffix
-   appended by the --stress option.
-
- - Defines standard test helper functions for your scripts to
-   use.  These functions are designed to make all scripts behave
-   consistently when command line arguments --verbose (or -v),
-   --debug (or -d), and --immediate (or -i) is given.
-
-Do's & don'ts
--------------
-
-Here are a few examples of things you probably should and shouldn't do
-when writing tests.
-
-Here are the "do's:"
-
- - Put all code inside test_expect_success and other assertions.
-
-   Even code that isn't a test per se, but merely some setup code
-   should be inside a test assertion.
-
- - Chain your test assertions
-
-   Write test code like this:
-
-	git merge foo &&
-	git push bar &&
-	test ...
-
-   Instead of:
-
-	git merge hla
-	git push gh
-	test ...
-
-   That way all of the commands in your tests will succeed or fail. If
-   you must ignore the return value of something, consider using a
-   helper function (e.g. use sane_unset instead of unset, in order
-   to avoid unportable return value for unsetting a variable that was
-   already unset), or prepending the command with test_might_fail or
-   test_must_fail.
-
- - Check the test coverage for your tests. See the "Test coverage"
-   below.
-
-   Don't blindly follow test coverage metrics; if a new function you added
-   doesn't have any coverage, then you're probably doing something wrong,
-   but having 100% coverage doesn't necessarily mean that you tested
-   everything.
-
-   Tests that are likely to smoke out future regressions are better
-   than tests that just inflate the coverage metrics.
-
- - When a test checks for an absolute path that a git command generated,
-   construct the expected value using $(pwd) rather than $PWD,
-   $TEST_DIRECTORY, or $TRASH_DIRECTORY. It makes a difference on
-   Windows, where the shell (MSYS bash) mangles absolute path names.
-   For details, see the commit message of 4114156ae9.
-
- - Remember that inside the <script> part, the standard output and
-   standard error streams are discarded, and the test harness only
-   reports "ok" or "not ok" to the end user running the tests. Under
-   --verbose, they are shown to help debug the tests.
-
- - Be careful when you loop
-
-   You may need to verify multiple things in a loop, but the
-   following does not work correctly:
-
-	test_expect_success 'test three things' '
-	    for i in one two three
-	    do
-		test_something "$i"
-	    done &&
-	    test_something_else
-	'
-
-   Because the status of the loop itself is the exit status of the
-   test_something in the last round, the loop does not fail when
-   "test_something" for "one" or "two" fails.  This is not what you
-   want.
-
-   Instead, you can break out of the loop immediately when you see a
-   failure.  Because all test_expect_* snippets are executed inside
-   a function, "return 1" can be used to fail the test immediately
-   upon a failure:
-
-	test_expect_success 'test three things' '
-	    for i in one two three
-	    do
-		test_something "$i" || return 1
-	    done &&
-	    test_something_else
-	'
-
-   Note that we still &&-chain the loop to propagate failures from
-   earlier commands.
-
-
-And here are the "don'ts:"
-
- - Don't exit() within a <script> part.
-
-   The harness will catch this as a programming error of the test.
-   Use test_done instead if you need to stop the tests early (see
-   "Skipping tests" below).
-
- - Don't use '! git cmd' when you want to make sure the git command
-   exits with failure in a controlled way by calling "die()".  Instead,
-   use 'test_must_fail git cmd'.  This will signal a failure if git
-   dies in an unexpected way (e.g. segfault).
-
-   On the other hand, don't use test_must_fail for running regular
-   platform commands; just use '! cmd'.  We are not in the business
-   of verifying that the world given to us sanely works.
-
- - Don't feed the output of a git command to a pipe, as in:
-
-     git -C repo ls-files |
-     xargs -n 1 basename |
-     grep foo
-
-   which will discard git's exit code and may mask a crash. In the
-   above example, all exit codes are ignored except grep's.
-
-   Instead, write the output of that command to a temporary
-   file with ">" or assign it to a variable with "x=$(git ...)" rather
-   than pipe it.
-
- - Don't use command substitution in a way that discards git's exit
-   code. When assigning to a variable, the exit code is not discarded,
-   e.g.:
-
-     x=$(git cat-file -p $sha) &&
-     ...
-
-   is OK because a crash in "git cat-file" will cause the "&&" chain
-   to fail, but:
-
-     test "refs/heads/foo" = "$(git symbolic-ref HEAD)"
-
-   is not OK and a crash in git could go undetected.
-
- - Don't use perl without spelling it as "$PERL_PATH". This is to help
-   our friends on Windows where the platform Perl often adds CR before
-   the end of line, and they bundle Git with a version of Perl that
-   does not do so, whose path is specified with $PERL_PATH. Note that we
-   provide a "perl" function which uses $PERL_PATH under the hood, so
-   you do not need to worry when simply running perl in the test scripts
-   (but you do, for example, on a shebang line or in a sub script
-   created via "write_script").
-
- - Don't use sh without spelling it as "$SHELL_PATH", when the script
-   can be misinterpreted by broken platform shell (e.g. Solaris).
-
- - Don't chdir around in tests.  It is not sufficient to chdir to
-   somewhere and then chdir back to the original location later in
-   the test, as any intermediate step can fail and abort the test,
-   causing the next test to start in an unexpected directory.  Do so
-   inside a subshell if necessary.
-
- - Don't save and verify the standard error of compound commands, i.e.
-   group commands, subshells, and shell functions (except test helper
-   functions like 'test_must_fail') like this:
-
-     ( cd dir && git cmd ) 2>error &&
-     test_cmp expect error
-
-   When running the test with '-x' tracing, then the trace of commands
-   executed in the compound command will be included in standard error
-   as well, quite possibly throwing off the subsequent checks examining
-   the output.  Instead, save only the relevant git command's standard
-   error:
-
-     ( cd dir && git cmd 2>../error ) &&
-     test_cmp expect error
-
- - Don't break the TAP output
-
-   The raw output from your test may be interpreted by a TAP harness. TAP
-   harnesses will ignore everything they don't know about, but don't step
-   on their toes in these areas:
-
-   - Don't print lines like "$x..$y" where $x and $y are integers.
-
-   - Don't print lines that begin with "ok" or "not ok".
-
-   TAP harnesses expect a line that begins with either "ok" and "not
-   ok" to signal a test passed or failed (and our harness already
-   produces such lines), so your script shouldn't emit such lines to
-   their output.
-
-   You can glean some further possible issues from the TAP grammar
-   (see https://metacpan.org/pod/TAP::Parser::Grammar#TAP-GRAMMAR)
-   but the best indication is to just run the tests with prove(1),
-   it'll complain if anything is amiss.
-
-
-Skipping tests
---------------
-
-If you need to skip tests you should do so by using the three-arg form
-of the test_* functions (see the "Test harness library" section
-below), e.g.:
-
-    test_expect_success PERL 'I need Perl' '
-        perl -e "hlagh() if unf_unf()"
-    '
-
-The advantage of skipping tests like this is that platforms that don't
-have the PERL and other optional dependencies get an indication of how
-many tests they're missing.
-
-If the test code is too hairy for that (i.e. does a lot of setup work
-outside test assertions) you can also skip all remaining tests by
-setting skip_all and immediately call test_done:
-
-	if ! test_have_prereq PERL
-	then
-	    skip_all='skipping perl interface tests, perl not available'
-	    test_done
-	fi
-
-The string you give to skip_all will be used as an explanation for why
-the test was skipped.
-
-End with test_done
-------------------
-
-Your script will be a sequence of tests, using helper functions
-from the test harness library.  At the end of the script, call
-'test_done'.
-
-
-Test harness library
---------------------
-
-There are a handful helper functions defined in the test harness
-library for your script to use.
-
- - test_expect_success [<prereq>] <message> <script>
-
-   Usually takes two strings as parameters, and evaluates the
-   <script>.  If it yields success, test is considered
-   successful.  <message> should state what it is testing.
-
-   Example:
-
-	test_expect_success \
-	    'git-write-tree should be able to write an empty tree.' \
-	    'tree=$(git-write-tree)'
-
-   If you supply three parameters the first will be taken to be a
-   prerequisite; see the test_set_prereq and test_have_prereq
-   documentation below:
-
-	test_expect_success TTY 'git --paginate rev-list uses a pager' \
-	    ' ... '
-
-   You can also supply a comma-separated list of prerequisites, in the
-   rare case where your test depends on more than one:
-
-	test_expect_success PERL,PYTHON 'yo dawg' \
-	    ' test $(perl -E 'print eval "1 +" . qx[python -c "print 2"]') == "4" '
-
- - test_expect_failure [<prereq>] <message> <script>
-
-   This is NOT the opposite of test_expect_success, but is used
-   to mark a test that demonstrates a known breakage.  Unlike
-   the usual test_expect_success tests, which say "ok" on
-   success and "FAIL" on failure, this will say "FIXED" on
-   success and "still broken" on failure.  Failures from these
-   tests won't cause -i (immediate) to stop.
-
-   Like test_expect_success this function can optionally use a three
-   argument invocation with a prerequisite as the first argument.
-
- - test_debug <script>
-
-   This takes a single argument, <script>, and evaluates it only
-   when the test script is started with --debug command line
-   argument.  This is primarily meant for use during the
-   development of a new test script.
-
- - debug <git-command>
-
-   Run a git command inside a debugger. This is primarily meant for
-   use when debugging a failing test script.
-
- - test_done
-
-   Your test script must have test_done at the end.  Its purpose
-   is to summarize successes and failures in the test script and
-   exit with an appropriate error code.
-
- - test_tick
-
-   Make commit and tag names consistent by setting the author and
-   committer times to defined state.  Subsequent calls will
-   advance the times by a fixed amount.
-
- - test_commit <message> [<filename> [<contents>]]
-
-   Creates a commit with the given message, committing the given
-   file with the given contents (default for both is to reuse the
-   message string), and adds a tag (again reusing the message
-   string as name).  Calls test_tick to make the SHA-1s
-   reproducible.
-
- - test_merge <message> <commit-or-tag>
-
-   Merges the given rev using the given message.  Like test_commit,
-   creates a tag and calls test_tick before committing.
-
- - test_set_prereq <prereq>
-
-   Set a test prerequisite to be used later with test_have_prereq. The
-   test-lib will set some prerequisites for you, see the
-   "Prerequisites" section below for a full list of these.
-
-   Others you can set yourself and use later with either
-   test_have_prereq directly, or the three argument invocation of
-   test_expect_success and test_expect_failure.
-
- - test_have_prereq <prereq>
-
-   Check if we have a prerequisite previously set with test_set_prereq.
-   The most common way to use this explicitly (as opposed to the
-   implicit use when an argument is passed to test_expect_*) is to skip
-   all the tests at the start of the test script if we don't have some
-   essential prerequisite:
-
-	if ! test_have_prereq PERL
-	then
-	    skip_all='skipping perl interface tests, perl not available'
-	    test_done
-	fi
-
- - test_external [<prereq>] <message> <external> <script>
-
-   Execute a <script> with an <external> interpreter (like perl). This
-   was added for tests like t9700-perl-git.sh which do most of their
-   work in an external test script.
-
-	test_external \
-	    'GitwebCache::*FileCache*' \
-	    perl "$TEST_DIRECTORY"/t9503/test_cache_interface.pl
-
-   If the test is outputting its own TAP you should set the
-   test_external_has_tap variable somewhere before calling the first
-   test_external* function. See t9700-perl-git.sh for an example.
-
-	# The external test will outputs its own plan
-	test_external_has_tap=1
-
- - test_external_without_stderr [<prereq>] <message> <external> <script>
-
-   Like test_external but fail if there's any output on stderr,
-   instead of checking the exit code.
-
-	test_external_without_stderr \
-	    'Perl API' \
-	    perl "$TEST_DIRECTORY"/t9700/test.pl
-
- - test_expect_code <exit-code> <command>
-
-   Run a command and ensure that it exits with the given exit code.
-   For example:
-
-	test_expect_success 'Merge with d/f conflicts' '
-		test_expect_code 1 git merge "merge msg" B master
-	'
-
- - test_must_fail [<options>] <git-command>
-
-   Run a git command and ensure it fails in a controlled way.  Use
-   this instead of "! <git-command>".  When git-command dies due to a
-   segfault, test_must_fail diagnoses it as an error; "! <git-command>"
-   treats it as just another expected failure, which would let such a
-   bug go unnoticed.
-
-   Accepts the following options:
-
-     ok=<signal-name>[,<...>]:
-       Don't treat an exit caused by the given signal as error.
-       Multiple signals can be specified as a comma separated list.
-       Currently recognized signal names are: sigpipe, success.
-       (Don't use 'success', use 'test_might_fail' instead.)
-
- - test_might_fail [<options>] <git-command>
-
-   Similar to test_must_fail, but tolerate success, too.  Use this
-   instead of "<git-command> || :" to catch failures due to segv.
-
-   Accepts the same options as test_must_fail.
-
- - test_cmp <expected> <actual>
-
-   Check whether the content of the <actual> file matches the
-   <expected> file.  This behaves like "cmp" but produces more
-   helpful output when the test is run with "-v" option.
-
- - test_cmp_rev <expected> <actual>
-
-   Check whether the <expected> rev points to the same commit as the
-   <actual> rev.
-
- - test_line_count (= | -lt | -ge | ...) <length> <file>
-
-   Check whether a file has the length it is expected to.
-
- - test_path_is_file <path> [<diagnosis>]
-   test_path_is_dir <path> [<diagnosis>]
-   test_path_is_missing <path> [<diagnosis>]
-
-   Check if the named path is a file, if the named path is a
-   directory, or if the named path does not exist, respectively,
-   and fail otherwise, showing the <diagnosis> text.
-
- - test_when_finished <script>
-
-   Prepend <script> to a list of commands to run to clean up
-   at the end of the current test.  If some clean-up command
-   fails, the test will not pass.
-
-   Example:
-
-	test_expect_success 'branch pointing to non-commit' '
-		git rev-parse HEAD^{tree} >.git/refs/heads/invalid &&
-		test_when_finished "git update-ref -d refs/heads/invalid" &&
-		...
-	'
-
- - test_atexit <script>
-
-   Prepend <script> to a list of commands to run unconditionally to
-   clean up before the test script exits, e.g. to stop a daemon:
-
-	test_expect_success 'test git daemon' '
-		git daemon &
-		daemon_pid=$! &&
-		test_atexit 'kill $daemon_pid' &&
-		hello world
-	'
-
-   The commands will be executed before the trash directory is removed,
-   i.e. the atexit commands will still be able to access any pidfiles or
-   socket files.
-
-   Note that these commands will be run even when a test script run
-   with '--immediate' fails.  Be careful with your atexit commands to
-   minimize any changes to the failed state.
-
- - test_write_lines <lines>
-
-   Write <lines> on standard output, one line per argument.
-   Useful to prepare multi-line files in a compact form.
-
-   Example:
-
-	test_write_lines a b c d e f g >foo
-
-   Is a more compact equivalent of:
-	cat >foo <<-EOF
-	a
-	b
-	c
-	d
-	e
-	f
-	g
-	EOF
-
-
- - test_pause
-
-	This command is useful for writing and debugging tests and must be
-	removed before submitting. It halts the execution of the test and
-	spawns a shell in the trash directory. Exit the shell to continue
-	the test. Example:
-
-	test_expect_success 'test' '
-		git do-something >actual &&
-		test_pause &&
-		test_cmp expected actual
-	'
-
- - test_ln_s_add <path1> <path2>
-
-   This function helps systems whose filesystem does not support symbolic
-   links. Use it to add a symbolic link entry to the index when it is not
-   important that the file system entry is a symbolic link, i.e., instead
-   of the sequence
-
-	ln -s foo bar &&
-	git add bar
-
-   Sometimes it is possible to split a test in a part that does not need
-   the symbolic link in the file system and a part that does; then only
-   the latter part need be protected by a SYMLINKS prerequisite (see below).
-
- - test_oid_init
-
-   This function loads facts and useful object IDs related to the hash
-   algorithm(s) in use from the files in t/oid-info.
-
- - test_oid_cache
-
-   This function reads per-hash algorithm information from standard
-   input (usually a heredoc) in the format described in
-   t/oid-info/README.  This is useful for test-specific values, such as
-   object IDs, which must vary based on the hash algorithm.
-
-   Certain fixed values, such as hash sizes and common placeholder
-   object IDs, can be loaded with test_oid_init (described above).
-
- - test_oid <key>
-
-   This function looks up a value for the hash algorithm in use, based
-   on the key given.  The value must have been loaded using
-   test_oid_init or test_oid_cache.  Providing an unknown key is an
-   error.
-
- - yes [<string>]
-
-   This is often seen in modern UNIX but some platforms lack it, so
-   the test harness overrides the platform implementation with a
-   more limited one.  Use this only when feeding a handful lines of
-   output to the downstream---unlike the real version, it generates
-   only up to 99 lines.
-
- - test_bool_env <env-variable-name> <default-value>
-
-   Given the name of an environment variable with a bool value,
-   normalize its value to a 0 (true) or 1 (false or empty string)
-   return code.  Return with code corresponding to the given default
-   value if the variable is unset.
-   Abort the test script if either the value of the variable or the
-   default are not valid bool values.
-
-
-Prerequisites
--------------
-
-These are the prerequisites that the test library predefines with
-test_have_prereq.
-
-See the prereq argument to the test_* functions in the "Test harness
-library" section above and the "test_have_prereq" function for how to
-use these, and "test_set_prereq" for how to define your own.
-
- - PYTHON
-
-   Git wasn't compiled with NO_PYTHON=YesPlease. Wrap any tests that
-   need Python with this.
-
- - PERL
-
-   Git wasn't compiled with NO_PERL=YesPlease.
-
-   Even without the PERL prerequisite, tests can assume there is a
-   usable perl interpreter at $PERL_PATH, though it need not be
-   particularly modern.
-
- - POSIXPERM
-
-   The filesystem supports POSIX style permission bits.
-
- - BSLASHPSPEC
-
-   Backslashes in pathspec are not directory separators. This is not
-   set on Windows. See 6fd1106a for details.
-
- - EXECKEEPSPID
-
-   The process retains the same pid across exec(2). See fb9a2bea for
-   details.
-
- - PIPE
-
-   The filesystem we're on supports creation of FIFOs (named pipes)
-   via mkfifo(1).
-
- - SYMLINKS
-
-   The filesystem we're on supports symbolic links. E.g. a FAT
-   filesystem doesn't support these. See 704a3143 for details.
-
- - SANITY
-
-   Test is not run by root user, and an attempt to write to an
-   unwritable file is expected to fail correctly.
-
- - PCRE
-
-   Git was compiled with support for PCRE. Wrap any tests
-   that use git-grep --perl-regexp or git-grep -P in these.
-
- - LIBPCRE1
-
-   Git was compiled with PCRE v1 support via
-   USE_LIBPCRE1=YesPlease. Wrap any PCRE using tests that for some
-   reason need v1 of the PCRE library instead of v2 in these.
-
- - LIBPCRE2
-
-   Git was compiled with PCRE v2 support via
-   USE_LIBPCRE2=YesPlease. Wrap any PCRE using tests that for some
-   reason need v2 of the PCRE library instead of v1 in these.
-
- - CASE_INSENSITIVE_FS
-
-   Test is run on a case insensitive file system.
-
- - UTF8_NFD_TO_NFC
-
-   Test is run on a filesystem which converts decomposed utf-8 (nfd)
-   to precomposed utf-8 (nfc).
-
- - PTHREADS
-
-   Git wasn't compiled with NO_PTHREADS=YesPlease.
-
-Tips for Writing Tests
-----------------------
-
-As with any programming projects, existing programs are the best
-source of the information.  However, do _not_ emulate
-t0000-basic.sh when writing your tests.  The test is special in
-that it tries to validate the very core of Git.  For example, it
-knows that there will be 256 subdirectories under .git/objects/,
-and it knows that the object ID of an empty tree is a certain
-40-byte string.  This is deliberately done so in t0000-basic.sh
-because the things the very basic core test tries to achieve is
-to serve as a basis for people who are changing the Git internals
-drastically.  For these people, after making certain changes,
-not seeing failures from the basic test _is_ a failure.  And
-such drastic changes to the core Git that even changes these
-otherwise supposedly stable object IDs should be accompanied by
-an update to t0000-basic.sh.
-
-However, other tests that simply rely on basic parts of the core
-Git working properly should not have that level of intimate
-knowledge of the core Git internals.  If all the test scripts
-hardcoded the object IDs like t0000-basic.sh does, that defeats
-the purpose of t0000-basic.sh, which is to isolate that level of
-validation in one place.  Your test also ends up needing
-updating when such a change to the internal happens, so do _not_
-do it and leave the low level of validation to t0000-basic.sh.
-
-Test coverage
--------------
-
-You can use the coverage tests to find code paths that are not being
-used or properly exercised yet.
-
-To do that, run the coverage target at the top-level (not in the t/
-directory):
-
-    make coverage
-
-That'll compile Git with GCC's coverage arguments, and generate a test
-report with gcov after the tests finish. Running the coverage tests
-can take a while, since running the tests in parallel is incompatible
-with GCC's coverage mode.
-
-After the tests have run you can generate a list of untested
-functions:
-
-    make coverage-untested-functions
-
-You can also generate a detailed per-file HTML report using the
-Devel::Cover module. To install it do:
-
-   # On Debian or Ubuntu:
-   sudo aptitude install libdevel-cover-perl
-
-   # From the CPAN with cpanminus
-   curl -L http://cpanmin.us | perl - --sudo --self-upgrade
-   cpanm --sudo Devel::Cover
-
-Then, at the top-level:
-
-    make cover_db_html
-
-That'll generate a detailed cover report in the "cover_db_html"
-directory, which you can then copy to a webserver, or inspect locally
-in a browser.