docs/technical/gc-mini.txt

   1 ==================================
   2 Mini Garbage Collection in Girocco
   3 ==================================
   4
   5 What is "mini" garbage collection?
   6
   7 A "mini" garbage collection makes the repository more efficient by cleaning
   8 up any "crud" files, combining small packs and joining per-push reflogs.
   9
  10 For "git-svn" mirrors, loose objects from the most recent `git svn fetch`
  11 operation are migrated into a pack.
  12
  13 All of these tasks are also performed during a "full" garbage collection.
  14
  15 The difference is that a "mini" garbage collection never removes any objects
  16 nor does it ever perform a reachability trace.  It also will not operate on
  17 any overly large packs.  As a result it's typically a relatively speedy
  18 operation (at least when compared to full garbage collection).
  19
  20 The `combine-packs.sh` script provides the ability to combine packs and/or pack
  21 loose objects into a pack.  It produces packs that are just as efficient as
  22 Git packs (within +/- 1%) but does not require connected objects to do so.
  23
  24 --------------------
  25 Triggering a Mini GC
  26 --------------------
  27
  28 There are two places a "mini" garbage collection can be triggered from:
  29
  30  1. The `pre-receive` hook scripts
  31  2. The `update.sh` mirror update script
  32
  33 (Technically the toolbox `perform-pre-gc-linking.sh` script can also trigger
  34 a "mini" garbage collection but it's not something that normally runs.)
  35
  36
  37 Requesting a Mini GC
  38 ~~~~~~~~~~~~~~~~~~~~
  39
  40 Once a "mini" garbage collection becomes desirable, it's requested simply by
  41 making sure the `.needsgc` file exists in the repository's git directory
  42 (i.e. alongside the `config` file) -- the contents of the `.needsgc` file are
  43 ignored.
  44
  45 When the `jobd.pl` process checks to see if a repository needs to have garbage
  46 collection run on it (by examining its `gitweb.lastgc` value) it will disregard
  47 the `gitweb.lastgc` value and always run the `gc.sh` script if it sees a
  48 `.needsgc` file is present.
  49
  50 When the `gc.sh` script is run, if the time for a full garbage collection has
  51 not yet arrived _and_ a `.needsgc` file exists then it will perform a "mini"
  52 garbage collection on the repository instead.
  53
  54
  55 Conditions causing a Mini GC
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57
  58 Since Girocco uses transfer.unpackLimit=1, it's possible for more packs than
  59 usual to build up more quickly since every successful push that is not strictly
  60 a rewind will leave a new pack behind.
  61
  62 Once 20 (or more) packs are detected a "mini" garbage collection will be
  63 requested.
  64
  65 Every ref change fed to the `pre-receive` hook or caused by running the
  66 `update.sh` mirror update script gets recorded in a "reflogs" file located
  67 in the `reflogs` directory (located alongside the repository's git directory
  68 `config` file).
  69
  70 Each push operation generates a new "reflogs" file while each mirror update
  71 operation that receives new updates just appends to the current day's file.
  72
  73 Once 50 (or more) reflogs files are detected a "mini" garbage collection will
  74 be requested.
  75
  76 Any "git-svn" fetch operation that fetches any new loose objects will also
  77 immediately cause a "mini" garbage collection to be requested.
  78
  79 --------------------
  80 Escalating a Mini GC
  81 --------------------
  82
  83 The primary purpose of a "mini" garbage collection is to reduce the number
  84 of packs.
  85
  86 To remain efficient, a "mini" garbage collection ignores overly large packs
  87 and does not perform any object reachability traces nor does it ever remove
  88 any objects.
  89
  90 If a "mini" garbage collection cannot reduce the total number of "extra"
  91 packs to less than 10 it will trigger a full garbage collection the next
  92 time that `jobd.pl` services the repository (it does this by unsetting the
  93 `gitweb.lastgc` value).
  94
  95 When counting "extra" packs, any `.keep` packs or `.bitmap` or `.bndl`
  96 packs are excluded from the count to avoid disrupting incoming pushes,
  97 use of bitmaps or downloadable bundles.
  98
  99 ----------------------------
 100 On Demand Garbage Collection
 101 ----------------------------
 102
 103 The end result of the `.needsgc` facility and the ability to escalate to a full
 104 garbage collection when necessary effectively provides an "on-demand" garbage
 105 collection capability for Girocco.
 106
 107 As long as `jobd.pl` runs continuously (or often enough in `--all-once` mode),
 108 Girocco's repositories will generally be kept in a well-maintained state.