Documentation/git-rev-cache.txt

   1 git-rev-cache(1)
   2 ================
   3
   4 NAME
   5 ----
   6 git-rev-cache - Add, walk and maintain revision cache slices
   7
   8 SYNOPSIS
   9 --------
  10 'git-rev-cache' COMMAND [options] [<commit>...]
  11
  12 DESCRIPTION
  13 -----------
  14 The revision cache ('rev-cache') provides a mechanism for significantly
  15 speeding up revision traversals.  It does this by creating an efficient
  16 database (cache) of commits, their related objects and topological relations.
  17 Independant of packs and the object store, this database is composed of
  18 rev-cache "slices" -- each a different file storing a given segment of commit
  19 history.  To map commits to their respective slices, a single index file is
  20 kept for the rev-cache.
  21
  22 'git-rev-cache' provides a front-end for the rev-cache mechanism, intended for
  23 updating and maintaining rev-cache slices in the current repository.  New cache
  24 slice files can be 'add'ed, to keep the cache up-to-date; individual slices can
  25 be traversed; smaller slices can be 'fuse'd into a larger slice; and the
  26 rev-cache index can be regenerated.
  27
  28 COMMANDS
  29 --------
  30
  31 add
  32 ~~~
  33 Add revisions to the cache by creating a new cache slice.  Reads a revision
  34 list from the command line, formatted as: `START START ... \--not END END ...`
  35
  36 Options
  37 ^^^^^^^
  38
  39 \--all::
  40         Include all refs in the new cache slice, like the \--all option in
  41         'rev-list'.
  42
  43 \--fresh/\--incremental::
  44         Exclude everything already in the revision cache, analogous to
  45         \--incremental in 'pack-objects'.
  46
  47 \--stdin::
  48         Read newline-seperated revisions from the standard input.  Use \--not
  49         to exclude commits, as on the command line.
  50
  51 \--legs::
  52         Ensure newly-generated cache slice has no partial ends.  This means that
  53         no commit has partially cached parents, in that all its parents are
  54         cached or none of them are.  99.9% of users can ignore this command.
  55 +
  56 \--legs will cause 'rev-cache' to expand potential slice end-points (creating
  57 "legs") until this condition is met, simplifying the cache slice structure.
  58 'rev-cache' itself does not care if a slice has legs or not, but the condition
  59 may reduce the required complexity of other applications that might use the
  60 revision cache.
  61
  62 \--no-objects::
  63         Non-commit objects are normally included along with the commit with
  64         which they were introduced.  This is obviously very benificial, but can
  65         take longer in cache slice generation.  Using this option will disable
  66         non-commit object caching.
  67 +
  68 \--no-objects is mainly intended for debugging or development purposes, but may
  69 find use in special situations (e.g. common traversal of only commits).
  70
  71 Output
  72 ^^^^^^
  73
  74 On `stderr` 'add' outputs general information about the generated slice,
  75 including the number of objects and paths, and the start/end commits (prefix S
  76 indicates start, E an end).  Through `stdout` it emits only the SHA-1 of the
  77 slice.
  78
  79 walk
  80 ~~~~
  81 Analogous to a slice-oriented 'rev-list', 'walk' will traverse a region in a
  82 particular cache slice.  Interesting and uninteresting (delimited, as with
  83 'rev-list', with \--not) are specified on the command line, and output is the
  84 same as vanilla 'rev-list'.
  85
  86 Options
  87 ^^^^^^^
  88
  89 \--objects::
  90         Like 'rev-list', 'walk' will normally only list commits.  Use this
  91         option to list non-commit objects as well, if they are present in the
  92         cache slice.
  93
  94 Output
  95 ^^^^^^
  96
  97 'walk' will simply dump the contents of the output commit list, work list, and
  98 pending object array.  The headers are outputed on `stderr`, the object hashes
  99 and names on `stdout`.
 100
 101 fuse
 102 ~~~~
 103 Merge several cache slices into a single large slice, like 'repack' for
 104 'rev-cache'.  On each invocation of 'add' a new file ("slice") is added to the
 105 revision cache directory, and after several additions the directory may become
 106 populated with many, relatively small slices.  Numerous smaller slices will
 107 yield poorer performance than a one or two large ones, because of the overhead
 108 of loading new slices into memory.
 109
 110 Running 'fuse' every once in a while will solve this problem by coalescing all
 111 the cache slices into one larger slice.  For very large projects, using
 112 \--ignore-size is advisable to prevent overly large cache slices.  This can be
 113 set to run on garbage collection; see 'Automation' for more info.
 114
 115 Note that 'fuse' uses the internal revision walker, so the options used in
 116 fusion override those of the cache slices upon which it operates.  For example,
 117 if some slices were generated with \--no-objects, yet 'fuse' was performed with
 118 non-commit objects, the resulting slice would still contain objects but would
 119 take longer to generate.
 120
 121 Options
 122 ^^^^^^^
 123
 124 \--all::
 125         Normally fuse will only include everything that's already in the
 126         revision cache.  \--all tells it to start walking from the branch
 127         heads, effectively a `add --all --fresh; fuse`
 128         (pseudo-revcache-command).
 129
 130 \--no-objects::
 131         As in 'add', this option disables inclusion of non-commit objects.  If
 132         some cache slices do contain such objects, the information will be lost.
 133
 134 \--ignore-size[=N]::
 135         Do not merge cache slices of size >=N (be aware that slices must be
 136         mapped to memory).  N can have a suffix of "k" or "m", denoting N as
 137         kilobytes and megabytes, respectively.  If N is not provided 'fuse'
 138         will default to a size specified in `revcache.ignoresize`, or ~25MB if
 139         the config var is not set.
 140
 141 Output
 142 ^^^^^^
 143
 144 This command prints the SHA-1 of the new slice on `stdout`, and information
 145 about its work on `stderr` -- specifically which files it's removing.
 146
 147 Automation
 148 ^^^^^^^^^^
 149
 150 Set the git configuration variable `gc.revcache` to run 'fuse' on garbage
 151 collection.  The arguments passed are `fuse \--all \--ignore-size`; i.e. 'gc'
 152 will keep everything cached into size-regulated slices.
 153
 154 index
 155 ~~~~~
 156 Regenerate the revision cache index.  If the rev-cache index file associating
 157 objects with cache slices gets corrupted, lost, or otherwise becomes unusable,
 158 'index' will quickly regenerate the file.  It's most likely that this won't be
 159 needed in every day use, as it is targeted towards debugging and development.
 160
 161 alt
 162 ~~~
 163 Create a cache slice pointer to another slice, identified by its full path:
 164 `fuse path/to/other/slice`
 165
 166 This command is useful if you have several repositories sharing a common
 167 history.  Although space requirements for rev-cache are slim anyway, you can in
 168 this situation reduce it further by using slice pointers, pointing to relavant
 169 slices in other repositories.  Note that only one level of redirection is
 170 allowed, and the slice pointer will break if the original slice is removed.
 171 'fuse' will not touch slice pointers.
 172
 173 NOTES
 174 -----
 175 In certain circumstances there may be some inconsistencies with object names
 176 between cached and non-cached walks.  Specifically, if two objects in a commit
 177 tree have the same content (= same SHA-1); or if objects of the same SHA-1 are
 178 introduced independantly in parallel branches.
 179
 180 In the first case rev-cache will use the name of the youngest file, while
 181 vanilla rev-list will return the name of the entry first encountered in walking
 182 the tree.  The latter case is a result of rev-cache's internal topological
 183 ordering: the difference is the same between sorted and unsorted revision walks.
 184
 185 See 'Discussion' for the underlying reasons for the discrepencies.
 186
 187 DISCUSSION
 188 ----------
 189 For an explanation of the API and its inner workings, see
 190 link:technical/rev-cache.txt[technical info on rev-cache].