FORMAT

   1 Topbloke patch is:
   2         - branch in refs/topbloke-tips/<full-name>
   3                 contains the working version, fast-forwarding
   4         - branch in refs/topbloke-bases/<full-name>
   5                 contains the base version, being the pulling
   6                 merge of all the bases
   7
   8 In-tree, there are metadata files in .topbloke
   9
  10     Files which are per-patch and do not inherit any contents
  11     or changes from bases or dependencies:
  12
  13         msg             patch "commit message"
  14                         ("# not applicable" in bases)
  15
  16         deps            direct dependencies, one per line
  17                         as either:
  18                                 <topbloke patch name>
  19                                 .f <ref name including refs/heads/>
  20                                 .tg <ref name not including refs/heads/>
  21                         (empty in base branches)
  22
  23         deleted         exists (but empty) if branch is deleted
  24                         exist in tip only branch
  25
  26         patch-          name of this topbloke patch (plus a newline)
  27                         exists in base and tip
  28
  29         topgit-         name of the topgit branch that this was
  30                         imported from and which we should merge from
  31                         (plus a newline); exists in tip only
  32
  33         [^+]*-          another property that applies to this patch;
  34                         if not known to this version of topbloke then it
  35                         is safe to:
  36                           - merge this file as text when merging
  37                             from base into base or tip into tip
  38                           - throw away this file when merging from
  39                             base into tip or from dep into base
  40
  41     Files which inherit contents and changes from dependencies
  42     have names starting with "+":
  43
  44         +included       actual included deps, one per line
  45                                 format as for deps
  46
  47         +*-             another property that is inherited; it is also
  48                         safe to:
  49                          - merge this file as text when merging
  50                            from tb deps into bases or bases into tips
  51
  52
  53 <full-name> has the format:
  54         <email>@<domain.name>/<yyyy>-<mm>-<dd>T<hh><mm><ss>Z/<nickname-path>
  55 where nickname-path's first component must not start with a digit
  56 contain ~ or @  (: is not allowed in refs hence the squashing)
  57 eg
  58         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
  59 NB only exactly that date format is allowed and timezone must be Z.
  60
  61 Patches may be specified as
  62         [<qualifier>/...][<nickname-path-spec>]
  63 where <qualifier>/ is one of
  64         [<email>]@[<domain.name>/
  65                 Only patches matching the specified email local part
  66                 or domain name match
  67         [<date-spec>/]
  68                 A prefix of the ISO8601 date spec, stopping
  69                 just after a numeric component (or at the end)
  70         [<approx-date-containing-~>/]
  71                 Intepreted by date -d after ~s have been replaced by
  72                 spaces.  When we come to select, take the patch
  73                 nearest that date rather than the most recent
  74
  75
  76 <nickname-path-spec> may be
  77         <nickname-path>
  78         ./<nickname-new-leaf-component>
  79         ../<nickname-path-spec>
  80
  81 <date-spec> may be
  82         <approximate date spec containing at least one ~>
  83                 means all patches are candidates
  84
  85 So overall, if the current patch is
  86         ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
  87 then all of the following can refer to the same patch
  88         ./sponge
  89         ../reorg/sponge
  90         reorg/sponge
  91         2012/reorg/sponge
  92         2012/reorg/sponge
  93         2012/./sponge
  94         jan~/./sponge
  95         ijackson@/reorg/sponge
  96         ijackson@/2012/reorg/sponge
  97         ijackson@chiark.greenend.org.uk/reorg/sponge
  98         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
  99
 100 Search algorithm:
 101         1. prefer patches with email address (or domain)
 102            matching current patch
 103         2. prefer patches with our own email address (or domain)
 104         3. other patches
 105 Within this there may be patches with multiple dates; prefer the most
 106 recent.