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