Command: git test

• Description
• Usage
• Invoking
  • Command aliases
  • Default command
• Execution
  • Running outside the current working copy
  • Running in parallel
  • Caching
  • Showing output

Description

Available since v0.6.0.

git test is used to run a user-provided command on a given set of commits.

Usage

In its most basic form, run git test run --exec '<command>'. This will execute <command> on each commit in your current commit stack and display a summary of the results.

You can run on a different set of commits by specifying a different revset. For example: git test run -x '<command>' draft().

Invoking

Command aliases

You can pass --command <command> to run a pre-defined command alias instead of specifying the full command with --exec. Define a new alias with git config branchless.test.alias.<name> <command>, then run it with git test run --command <name>.

Default command

If neither --command nor --exec is provided, the default command alias is used.

Execution

Running outside the current working copy

There are two strategies for running the provided command:

• --strategy working-copy: Run in the working copy.
  • Only one instance of the command can run concurrently.
  • Useful if the working copy has build artifacts which should be preserved for each run.
  • Doesn't create any additional repository checkouts on disk.
• --strategy worktree: Run in a worktree managed by git-branchless.
  • Multiple instances of the command can run concurrently.
  • Untracked files such as build artifacts won't be shared between the working copy or different worktrees. However, build artifacts may be preserved in the same worktree for the next run.
  • Creates up to one extra repository checkout on disk per job.

You can set the default strategy with git config branchless.test.strategy <strategy>.

Running in parallel

You can pass --jobs N to run the command in parallel on different commits. A value of 0 indicates to select the number of jobs to run based on the number of CPUs on the machine. A value greater than one implies the worktree strategy.

You can set the default number of jobs with git config branchless.test.jobs <N>.

Caching

Each command invocation is cached using the command and the tree ID of the commit it ran on. If the command would run on a commit with the same tree again, the cached exit code and test output are immediately returned. This means that test commands won't re-run if only the commit message or ancestry have changed, but not the contents of the commit.

To delete cached results for a given commit, run git test clean <revset>.

Showing output

To show the results of previous test runs, run git test show -c/-x <command> <revset>. By default, only the passed/failed status is shown. To show the test output, pass -v/--verbose or -vv/--verbose --verbose for more detail.

You can also pass -v/-vv directly to git test run to show the output immediately after running.