git-annex/ git-annex-benchmark

# NAME

git-annex benchmark - benchmark git-annex commands

# SYNOPSIS

git annex benchmark [criterionopts] ( -- commmand [; command] | --databases=N )

# DESCRIPTION

When git-annex is built with benchmarking support, this command can be used to benchmark any other git-annex command. For example "git annex benchmark -- get ." will benchmark "git annex get".

The command being benchmarked is run in the current git-annex repository. It does not run just once; the benchmarking process will run it several times to get a statistically meaningful result.

When benchmarking an action like "git annex get", the first run will often do much more than subseqent runs. To make the benchmark repeat an action like getting a file each time, additional commands can be listed, separated by ';'. (Note that ';' needs to be escaped from the shell.) The combined script will be run repeatedly by the benchmark. An example of using this:

    git annex benchmark -- get . ';' drop .

Note that git-annex benchmark does not fork new git-annex processes when benchmarking; it calls the command to benchmark internally, and so avoids git-annex's startup overhead. (So don't try to use it to optimise git-annex startup.)

# OPTIONS

Before the "--" any of the criterion library's command-line options can be used.

Any options that git-annex usually accepts can be included after the command to benchmark.

The --databases=N option benchmark's git-annex's use of sqlite databases, instead of a command. N is the number of items to benchmark.

# OUTPUT

The output of the commands being benchmarked goes to standard output and standard error as usual. It's often a good idea to use --quiet to avoid unnecessary output, unless the generation of that output is part of what you want to benchmark.

The benchmark report is output to standard output by default, although criterion options can be used to redirect it to a file. For example:

    git annex benchmark -o bench -- find >/dev/null

# SEE ALSO

git-annex(1)

# AUTHOR

Joey Hess id@joeyh.name

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

comment 2

That --list turns out to come from the criterion library, and you can actually use it but only if you provide the mandatory "-- command" parameters too. For example:

    git-annex benchmark --list -- version
    version

That's not useful at all, since all if can list is the same benchmark you provide on input. But this is a consequence of supporting other criterion options like --iters and --csv that can be useful.

`git-annex benchmark` does not use a canned set of benchmarks; it benchmarks a git-annex subcommand or subcommands that you specify.

Comment by joey — Tue Jul 22 18:11:47 2025
comment 1

I see there is a `--list` command to list benchmarks but it just "errored out" with

    ❯ git annex benchmark --list
    Missing: COMMAND

    Usage: git-annex COMMAND
      git-annex - benchmarking
    ... here comes long list of all commands ...

of which that short `Usage:` help seems to be wrong (I did give the command) but I wonder what would be the invocation of `annex benchmark` if I were to run a collection of benchmarks to compare different filesystems, like I did in the past in https://www.datalad.org/test_fs_analysis.html?

FWIW git-annex version 10.20220724 (same with 10.20221003)

Comment by yarikoptic — Tue Jul 22 18:11:47 2025
Comments on this page are closed.