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             brach "commit message"
  14                         ("# not applicable" in bases)
  15
  16         deps            direct dependencies, one per line
  17                         as either:
  18                                 topbloke patch name
  19                                 /refs/heads/<something>
  20                         ("# not applicable" in bases)
  21
  22         flags           flags that apply to this patch, one per line
  23                         base has its own, perhaps different, set of flags;
  24                          Unknown flags starting with [a-z] are ok;
  25                          otherwise fatal.  Currently defined flags:
  26                                 Deleted         patch is deleted
  27                                                 (valid on tip only)
  28
  29     Files which not inherit contents and changes from dependencies:
  30
  31         included        actual included deps, one per line
  32                                 format as for deps
  33
  34         pflags          flags that apply to this patch and all its
  35                         dependencies (ie, flags that propagate)
  36                          Unknown flags starting with [a-z] are ok;
  37                          otherwise fatal.  No currently defined flags
  38
  39
  40 <full-name> has the format:
  41         <email>@<domain.name>/<yyyy>-<mm>-<dd>T<hh><mm><ss>Z/<nickname-path>
  42 where nickname-path's first component must not start with a digit
  43 contain ~ or @  (: is not allowed in refs hence the squashing)
  44 eg
  45         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
  46 NB only exactly that date format is allowed and timezone must be Z.
  47
  48 Patches may be specified as
  49         [<qualifier>/...][<nickname-path-spec>]
  50 where <qualifier>/ is one of
  51         [<email>]@[<domain.name>/
  52                 Only patches matching the specified email local part
  53                 or domain name match
  54         [<date-spec>/]
  55                 A prefix of the ISO8601 date spec, stopping
  56                 just after a numeric component (or at the end)
  57         [<approx-date-containing-~>/]
  58                 Intepreted by date -d after ~s have been replaced by
  59                 spaces.  When we come to select, take the patch
  60                 nearest that date rather than the most recent
  61
  62
  63 <nickname-path-spec> may be
  64         <nickname-path>
  65         ./<nickname-new-leaf-component>
  66         ../<nickname-path-spec>
  67
  68 <date-spec> may be
  69         <approximate date spec containing at least one ~>
  70                 means all patches are candidates
  71
  72 So overall, if the current patch is
  73         ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
  74 then all of the following can refer to the same patch
  75         ./sponge
  76         ../reorg/sponge
  77         reorg/sponge
  78         2012/reorg/sponge
  79         2012/reorg/sponge
  80         2012/./sponge
  81         jan~/./sponge
  82         ijackson@/reorg/sponge
  83         ijackson@/2012/reorg/sponge
  84         ijackson@chiark.greenend.org.uk/reorg/sponge
  85         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
  86
  87 Search algorithm:
  88         1. prefer patches with email address (or domain)
  89            matching current patch
  90         2. prefer patches with our own email address (or domain)
  91         3. other patches
  92 Within this there may be patches with multiple dates; prefer the most
  93 recent.