GIT-TEST(1)

📦 version 1.0.4, in nixos 26.05, nixpkgs unstable

🎀 GIT-TEST(1) 🎀

okay bestie, welcome to the git-test manual — this is the User Commands page for git-test version 1.0.4, and yes we're gonna get into all of it. grab a snack. 💅

✨ NAME ✨

git-test — literally the whole manual page for git-test version 1.0.4, that's it, that's the name section 🫶

🌸 SYNOPSIS 🌸

git test [options] [refs...]

git test --clear [refs...]

git test --version

🦋 DESCRIPTION 🦋

So the vibe is: run tests on each distinct tree in a revision list. That's the whole pitch, and honestly? iconic. 👑

The 99% example is simply:

git test

If no refs are specified, the default operation is to test the commits on the current branch that are not in the origin branch of the same name, nor in origin/master. If neither origin/"current branch", nor origin/master exist, git-test will refuse to run in order to protect against surprisingly large runs. Bestie this is a real thing that would happen if, for instance, you're simply not using a remote named origin, in a large project with many versions. 💀

This is currently not configurable, but if you want any other ref, you can just supply it:

git test HEAD ^jeff/development

Note that ref exclusions are almost always necessary since not having them would mean testing everything since the dawn of time. 😭 (no literally, everything.)

For example, this will test all commits on master that have not been pushed to origin:

git test --verify="make test" master ^origin/master

Tests are assumed to be deterministic and git-test uses a cache of trees with known results to speed up testing. Having non-deterministic, "flappy" tests, is a very special circle of hell, but there are some limited facilities for dealing with this situation. (Besides the obvious, fixing your tests.) 🙈

Running with the verbose option shows progress as it happens:

$ git test
the-branch ^origin/the-branch ^origin/master will test 2 commits
iter commit  tree    result
0000 83d611b 718c490 ... pass
0001 0be28e9 6908e0d ... pass

Immediately re-running the tests will just take the results from the cache:

$ git test
the-branch ^origin/the-branch ^origin/master will test 2 commits
iter commit  tree    result
0000 83d611b 718c490 ... pass (cached)
0001 0be28e9 6908e0d ... pass (cached)

look at that caching go. she ate. 🍓

💜 CONFIGURATION 💜

To specify what to run on each tree, the arguments --pre, --post and --verify can be used to set housekeeping commands and a (required) verifying command. The result of the housekeeping commands are ignored, because it's often convenient to just let it fail if there is nothing to clean up, or there's no artifact to save, or whatever it is you were trying to do. no stress, no drama. 🧚

To avoid having to specify action(s) on every invocation, they can be set using git-config feature, preferrably locally:

git config test.verify "make test"

git config test.pre "rm -f test-output"

git config test.post "cp a.out a.out.\$commit"

Alternatively, these can be set through environment variables GIT_TEST_PRE, GIT_TEST_POST and GIT_TEST_VERIFY respectively. pick your fighter. 🫶

A default ref (usually a branch) to test against can be configured:

git config test.branch origin/release

A default ref can also be set for a specific branch:

git config branch.myfeature.test origin/staging

✨ OPTIONS ✨

Available options are 👇

  • -v, --verbose — be more explicit about what is going on (she's a talker, we love her)
  • -q, --quiet — be quiet (shhh 🤫)
  • -r, --redo ... — test if [any/pass/fail/both/never] result cached for tree. See the REDO MODES section
  • -o, --output ... — output directory for reports. See the SAVING OUTPUT section
  • --pre ..., --post ... — command to run before and after running the test. Overrides the environment variables GIT_TEST_PRE, GIT_TEST_POST and the git-config options test.pre, test.post
  • --verify ... — the command to run as test. Overrides the environment variable GIT_TEST_VERIFY and the git-config option test.verify

🌈 ACTIONS 🌈

  • --clear — clear the results cache (bye bye data 🧹)
  • --version — print version info and quit

🔥 REDO MODES 🔥

If the tests have false negatives, git-test can be instructed to re-test failing commits. For symmetry, re-test everything, (all or any) re-test passing tests and the default behavior to never re-test can be specified. yes bestie, there's a mode for every mood. 🎀

  • a, any, all, always — Always run all test
  • p, pass, passed, passing — Retest passed (and flappy) tests
  • f, fail, failed, failing — Retest failed (and flappy) tests
  • b, both, flap, flappy — Retest only flappy tests
  • n, no, none, never — Never retest, always trust cache

(Default: none)

🌸 SAVING OUTPUT 🌸

By adding -o/--output to specify where, you can tell git-test to save stdout and stderr from the actions in separate files by tree. 📁

Files are created for each tree and symlinked from commit and test-run timestamp directories.

Example:

reports/
|-- 1418737218
|   `-- 0000_pass -> ../tree/f864c32_4aab77c_pass
|   `-- 0001_pass -> ../tree/da47834_4aab77c_pass
|-- 1418737342
|   `-- 0000_pass -> ../tree/da47834_4aab77c_pass
|-- commit
|   `-- 6eaff36_pass -> ../tree/f864c32_4aab77c_pass
|   `-- 9d0234d_pass -> ../tree/da47834_4aab77c_pass
|-- latest -> 1418737342
`-- tree
    |-- da47834_4aab77c_pass
    `-- f864c32_4aab77c_pass

💅 CLEARING THE CACHE 💅

If refs are supplied when clearing the cache, the trees of the specified commits will be cleared, even though those exact trees may appear in other commits. It is what was requested and doing anything else would likely be prohibitively expensive and very confusing. so like… we're doing it the requested way, periodt. 💀

🫶 AUTHORS 🫶

Anders Eurenius <aes@eurenius.eu>

Copyright (C) 2015 Spotify AB Copyright (C) 2016 Anders Eurenius

⭐ LICENSE ⭐

Apache License 2.0

🧚 SEE ALSO 🧚

  • The full documentation for git-test is the source. Whether it conflicts with any other information or not, the computer will execute the code, never the documentation. read that again bestie. 😭
  • git-rebase(1), in particular, the exec feature
  • git-bisect(1) might also be of interest
  • For more information, please re-read.
fr fr, the source is the truth and this page is just the vibe. iykyk. 🌈

that's the whole page!! git-test version 1.0.4, dated August 2016, and this was GIT-TEST(1) — slay, go run some tests, mwah 💖✨

📦 where this page comes from