git.oblomov.eu Git - git/blob - t/perf/README

   1 Git performance tests
   2 =====================
   3
   4 This directory holds performance testing scripts for git tools.  The
   5 first part of this document describes the various ways in which you
   6 can run them.
   7
   8 When fixing the tools or adding enhancements, you are strongly
   9 encouraged to add tests in this directory to cover what you are
  10 trying to fix or enhance.  The later part of this short document
  11 describes how your test scripts should be organized.
  12
  13
  14 Running Tests
  15 -------------
  16
  17 The easiest way to run tests is to say "make".  This runs all
  18 the tests on the current git repository.
  19
  20     === Running 2 tests in this tree ===
  21     [...]
  22     Test                                     this tree
  23     ---------------------------------------------------------
  24     0001.1: rev-list --all                   0.54(0.51+0.02)
  25     0001.2: rev-list --all --objects         6.14(5.99+0.11)
  26     7810.1: grep worktree, cheap regex       0.16(0.16+0.35)
  27     7810.2: grep worktree, expensive regex   7.90(29.75+0.37)
  28     7810.3: grep --cached, cheap regex       3.07(3.02+0.25)
  29     7810.4: grep --cached, expensive regex   9.39(30.57+0.24)
  30
  31 You can compare multiple repositories and even git revisions with the
  32 'run' script:
  33
  34     $ ./run . origin/next /path/to/git-tree p0001-rev-list.sh
  35
  36 where . stands for the current git tree.  The full invocation is
  37
  38     ./run [<revision|directory>...] [--] [<test-script>...]
  39
  40 A '.' argument is implied if you do not pass any other
  41 revisions/directories.
  42
  43 You can also manually test this or another git build tree, and then
  44 call the aggregation script to summarize the results:
  45
  46     $ ./p0001-rev-list.sh
  47     [...]
  48     $ GIT_BUILD_DIR=/path/to/other/git ./p0001-rev-list.sh
  49     [...]
  50     $ ./aggregate.perl . /path/to/other/git ./p0001-rev-list.sh
  51
  52 aggregate.perl has the same invocation as 'run', it just does not run
  53 anything beforehand.
  54
  55 You can set the following variables (also in your config.mak):
  56
  57     GIT_PERF_REPEAT_COUNT
  58         Number of times a test should be repeated for best-of-N
  59         measurements.  Defaults to 3.
  60
  61     GIT_PERF_MAKE_OPTS
  62         Options to use when automatically building a git tree for
  63         performance testing.  E.g., -j6 would be useful.
  64
  65     GIT_PERF_REPO
  66     GIT_PERF_LARGE_REPO
  67         Repositories to copy for the performance tests.  The normal
  68         repo should be at least git.git size.  The large repo should
  69         probably be about linux.git size for optimal results.
  70         Both default to the git.git you are running from.
  71
  72 You can also pass the options taken by ordinary git tests; the most
  73 useful one is:
  74
  75 --root=<directory>::
  76         Create "trash" directories used to store all temporary data during
  77         testing under <directory>, instead of the t/ directory.
  78         Using this option with a RAM-based filesystem (such as tmpfs)
  79         can massively speed up the test suite.
  80
  81
  82 Naming Tests
  83 ------------
  84
  85 The performance test files are named as:
  86
  87         pNNNN-commandname-details.sh
  88
  89 where N is a decimal digit.  The same conventions for choosing NNNN as
  90 for normal tests apply.
  91
  92
  93 Writing Tests
  94 -------------
  95
  96 The perf script starts much like a normal test script, except it
  97 sources perf-lib.sh:
  98
  99         #!/bin/sh
 100         #
 101         # Copyright (c) 2005 Junio C Hamano
 102         #
 103
 104         test_description='xxx performance test'
 105         . ./perf-lib.sh
 106
 107 After that you will want to use some of the following:
 108
 109         test_perf_default_repo  # sets up a "normal" repository
 110         test_perf_large_repo    # sets up a "large" repository
 111
 112         test_perf_default_repo sub  # ditto, in a subdir "sub"
 113
 114         test_checkout_worktree  # if you need the worktree too
 115
 116 At least one of the first two is required!
 117
 118 You can use test_expect_success as usual. In both test_expect_success
 119 and in test_perf, running "git" points to the version that is being
 120 perf-tested. The $MODERN_GIT variable points to the git wrapper for the
 121 currently checked-out version (i.e., the one that matches the t/perf
 122 scripts you are running).  This is useful if your setup uses commands
 123 that only work with newer versions of git than what you might want to
 124 test (but obviously your new commands must still create a state that can
 125 be used by the older version of git you are testing).
 126
 127 For actual performance tests, use
 128
 129         test_perf 'descriptive string' '
 130                 command1 &&
 131                 command2
 132         '
 133
 134 test_perf spawns a subshell, for lack of better options.  This means
 135 that
 136
 137 * you _must_ export all variables that you need in the subshell
 138
 139 * you _must_ flag all variables that you want to persist from the
 140   subshell with 'test_export':
 141
 142         test_perf 'descriptive string' '
 143                 foo=$(git rev-parse HEAD) &&
 144                 test_export foo
 145         '
 146
 147   The so-exported variables are automatically marked for export in the
 148   shell executing the perf test.  For your convenience, test_export is
 149   the same as export in the main shell.
 150
 151   This feature relies on a bit of magic using 'set' and 'source'.
 152   While we have tried to make sure that it can cope with embedded
 153   whitespace and other special characters, it will not work with
 154   multi-line data.