git-annex/ git-annex-test

# NAME

git-annex test - run built-in test suite

# SYNOPSIS

git annex test

# DESCRIPTION

This runs git-annex's built-in test suite.

The test suite runs in the `.t` subdirectory of the current directory.

It can be useful to run the test suite on different filesystems, or to verify your local installation of git-annex.

# OPTIONS

There are several options, provided by Haskell's tasty test framework. Pass --help for details about those.

- `--jobs=N` `-JN`

  How many tests to run in parallel. The default is "cpus", which will runs one job per CPU core.

- `--keep-failures`

  When there are test failures, leave the `.t` directory populated with repositories that demonstate the failures, for later analysis.

- `--test-git-config name=value`

  The test suite prevents git from reading any git configuration files. Usually it is a good idea to run the test suite with a standard git configuration. However, this option can be useful to see what effect a git configuration setting has on the test suite.

  Some configuration settings will break the test suite, in ways that are due to a bug in git-annex. But it is possible that changing a configuration can find a legitimate bug in git-annex.

  One valid use of this is to change a git configuration to a value that is planned to be the new default in a future version of git.

  Also, some things can only be tested with a git configuration. For example, annex.shared-sop-command has to be set for the test suite to test using that command.

- `--test-debug`

  Normally output of commands run by the test suite is hidden, so even when annex.debug or --debug is enabled, it will not be displayed. This option makes the full output of commands run by the test suite be displayed. It also makes the test suite run git-annex with --debug.

  It's a good idea to use `-J1` in combinaton with this, otherwise the output of concurrent tests will be mixed together.

# SEE ALSO

git-annex(1)

git-annex-testremote(1)

# AUTHOR

Joey Hess id@joeyh.name

Warning: Automatically converted into a man page by mdwn2man. Edit with care.

comment 3
"since most threading related bugs are timing dependant, it's doubtful that the test suite would be able to usefully test them" -- if you repeat a test enough times it'll tell you whether that test might fail under multithreading. Then git bisect can narrow down the breaking change. But it'd be reassuring to be able to run the tests with multithreading on my particular environment (the way I use git-annex) and know they pass.
Comment by Ilya_Shlyakhter — Tue Jul 22 18:11:47 2025
comment 2

Multithreaded operation is not tested, and since most threading related bugs are timing dependant, it's doubtful that the test suite would be able to usefully test them.

Comment by joey — Tue Jul 22 18:11:47 2025
comment 1
Do the tests test multi-threaded operations (-JN)? Is here a way to specify the number of processors to use for testing?
Comment by Ilya_Shlyakhter — Tue Jul 22 18:11:47 2025
Comments on this page are closed.