{"id":18041307,"url":"https://github.com/ligurio/git-test","last_synced_at":"2025-04-09T16:50:29.402Z","repository":{"id":57434838,"uuid":"278631558","full_name":"ligurio/git-test","owner":"ligurio","description":"Run automated tests against a range of Git commits and keep track of the results ","archived":false,"fork":false,"pushed_at":"2020-07-14T12:12:57.000Z","size":90,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T18:54:17.887Z","etag":null,"topics":["git","python","regression-testing","testing"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/git-test/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ligurio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-10T12:46:01.000Z","updated_at":"2022-07-12T10:05:09.000Z","dependencies_parsed_at":"2022-09-04T15:04:57.782Z","dependency_job_id":null,"html_url":"https://github.com/ligurio/git-test","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ligurio%2Fgit-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ligurio%2Fgit-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ligurio%2Fgit-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ligurio%2Fgit-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ligurio","download_url":"https://codeload.github.com/ligurio/git-test/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248072485,"owners_count":21043243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","python","regression-testing","testing"],"created_at":"2024-10-30T15:09:07.271Z","updated_at":"2025-04-09T16:50:29.384Z","avatar_url":"https://github.com/ligurio.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `git test`\n\n`git-test` is a command-line script for running automated tests against commits\nin a Git repository. It is especially targeted at developers who like their\ntests to pass on *every* commit in a branch, not just the branch tip.\n\nThe best way to use `git test` is to keep a window open in a second linked\nworktree of your repository, and as often as you like run\n\n    git test run master..mybranch\n\n`git test` will test the commits in the specified range, reporting any\nfailures. The pass/fail results of running tests are also recorded permanently\nin your repository as Git \"notes\" (see `git-notes(1)`).\n\nIf a commit in the range has already been tested, then by default `git test`\nreports the old results rather than testing it again. This means that you can\nrun the above command over and over as you work, and `git test` won't repeat\ntests whose results it already knows. (Of course there are options to allow you\nto request explicitly that commits be retested.)\n\nThe test results are recorded by the *tree* that was tested, not the commit, so\nold test results remain valid even across some kinds of commit rewriting:\n\n* If commits are rewritten to change their log messages, authorship, dates,\netc., the test results remain valid.\n* If consecutive commits are squashed, the results remain valid.\n* If a commit is split into two, only the first (partial) commit needs to be\ntested.\n* If some commits deep in a branch are reordered, the test results for commits\nbuilt on top of the reordered commits often remain valid.\n\nOf course this means that your tests should not depend on things besides the\nfiles in the tree. For example, whether your test passes/fails should *not*\ndepend on the current branch name or commit message.\n\n## Usage\n\n### Defining tests\n\nFirst define the test that you would like to run; for example,\n\n    git test add \"make -j8 \u0026\u0026 make test\"\n\nThe string that you specify can be an arbitrary command; it is run with `sh\n-c`. Its exit code should be 0 if the test passes, or nonzero if it fails. The\ntest definition is stored in your Git config.\n\n### Test one or more commits\n\nBy default, `git test run` tests `HEAD`:\n\n    git test run\n\n(If the working copy is dirty, the test is run anyway but the results are not\nrecorded.)\n\nYou can test a range of Git commits with a single command:\n\n    git test run commit1..commit2\n\nThe test is run against each commit in the range, in order from old to new. If\na commit fails the test, `git test` reports the error and stops with the broken\ncommit checked out. You can also specify individual commits to test:\n\n    git test run commit1 commit2 commit3\n\nor test an arbitrary set of commits supplied via standard input:\n\n    git rev-list feature1 feature2 ^master | git test run --stdin\n\nYou can adjust the verbosity of the output using the `--verbosity`/`-v` or\n`--quiet`/`-q` options. Either of these options can be specified multiple\ntimes.\n\n### Define multiple tests\n\nYou can define multiple tests in a single repository (e.g., cheap vs. expensive\ntests). Their results are kept separate. By default, the test called `default`\nis run, but you can specify a different test to add/run using the\n`--test=\u003cname\u003e`/`-t \u003cname\u003e` option:\n\n    git test add \"make test\"\n    git test run commit1..commit2\n    git test add --test=build \"make\"\n    git test run --test=build commit1..commit2\n\n### Retrying tests and/or forgetting old test results\n\nIf you have flaky tests that occasionally fail for bogus reasons, you might\nwant to re-run the test against a commit even though `git test` has already\nrecorded a result for that commit. To do so, run `git test run` with the\n`--force`/`-f` or `--retest` options.\n\nIf you want to forget particular old test results without retesting, run `git\ntest run` with the `--forget` option.\n\nIf you want to permanently forget *all* stored results for a particular test\n(e.g., if something in your environment has changed), run\n\n    git test forget-results [--test=\u003cname\u003e]\n\n### Continue on test failures\n\nNormally, `git test run` stops at the first broken commit that it finds. If\nyou'd prefer for it to continue even after a failure, use the\n`--keep-going`/`-k` option.\n\n### Removing tests\n\nTo permanently remove a test definition and all of its stored results, run\n\n    git test remove [--test=\u003cname\u003e]\n\n### For help\n\nGeneral help about `git test` can be obtained by running\n\n    git test help\n\nHelp about a particular subcommand can be obtained via either\n\n    git test help run\n\nor\n\n    git test run --help\n\n\n## Best practice: use `git test` in a linked worktree\n\n`git test` works really well together with `git worktree`. Keep a second\nworktree and use it for testing your current branch continuously as you work:\n\n    git worktree add --detach ../test HEAD\n    cd ../test\n    git test run master..mybranch\n\nThe last command can be re-run any time; it only does significant work when\nsomething changes on your branch. Plus, with this setup you can continue to\nwork in your main working tree while the tests run.\n\nBecause linked worktrees share branches and the git configuration with the main\nrepository, test definitions and test results are visible across all worktrees.\nSo you could even run multiple tests at the same time in multiple linked\nworktrees.\n\n\n## Installation\n\nRequirements:\n\n* A recent Git command-line client\n* A Python interpreter. `git test` has been tested with Python versions 2.7 and\n3.4. It will probably work with any Python3 version starting with 3.2 (it\nrequires `argparse`).\n\nJust put `bin/git-test` somewhere in your `$PATH`, adjusting its first line if\nnecessary to invoke the desired Python interpreter properly in your\nenvironment.\n\n## Ideas for future enhancements\n\nSome other features that would be nice:\n\n* Be more consistent about restoring `HEAD`. `git test run` currently checks\nout the branch that you started on when it is finished, but only if all of the\ntests passed. We need some kind of `git test reset` command analogous to `git\nbisect reset`.\n\n* `git test bisect`: run `git bisect run` against a range of commits, using a\nconfigured test as the command that `bisect` uses to decide whether a commit is\ngood/bad.\n\n* `git test prune`: delete notes for obsolete trees.\n\n* Continuous testing mode, where `git test` watches the repository for changes\nand re-runs itself automatically whenever the commits it is watching change.\n\n* Dependencies between tests; for example:\n    * Provide a way to say \"if my `full` test passes, that implies that the\n`build` test would also pass\".\n    * Provide a way to run the `build` test (and record the `build` test's\nresults) as the first step of the `full` test.\n* Allow trees to be marked `skip`, if they shouldn't be tested (e.g., due to a\nknown breakage). Perhaps allow the test script to emit a special return code to\nask that the commit be marked `skip` (probably following the convention of `git\nbisect run`).\n\n* Remember return codes and give them back out if the old result is reused.\n\n* Add a `git test fix \u003crange\u003e`, which starts an interactive rebase, changing\nthe command for the first broken commit from \"pick\" to \"edit\".\n\n* Support tests that depend on the *commit*, not the *tree*, that they are run\nagainst.\n\n\n## License\n\n`git test` is released under the GPLv2+ license. Pull requests are welcome at\nthe project's GitHub page, https://github.com/ligurio/git-test\n\n\n## Caveats and disclaimers\n\n`git test` has pretty good automated tests, but it undoubtedly still has bugs\nand rough edges. Use it at your own risk.\n\nPlease note that when you tell `git test run` to test specified commits, it\nchecks those commits out in your working directory. If the tests fail, it\nleaves the failing commit checked out *in a detached HEAD state*. This is\nintentional, so that you can examine the cause of the failure. But it means\nthat if you had changes on your original HEAD that weren't part of any branch,\nthey will now be unreachable.\n\nIf you don't know what a detached HEAD state is, please read up on it.\nAdditionally, **it is recommended that you run `git test` in a separate\nworktree**, which is more convenient anyway (see above for instructions). Note\nthat the `git worktree` command was added in Git release 2.5, so make sure you\nare using that version of Git or (preferably) newer.\n\nThe above considerations don't apply to running `git test` against HEAD or your\ncurrent working tree. In other words,\n\n    git test run\n\nand\n\n    git test run HEAD\n\ndon't change the commit that is checked out, and they won't change your working\ncopy to a detached HEAD state.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fligurio%2Fgit-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fligurio%2Fgit-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fligurio%2Fgit-test/lists"}