FORMAT

   1 Topbloke branch 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-branch 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 branch name
  19                                 /refs/heads/<something>
  20                         ("# not applicable" in bases)
  21
  22         flags           flags that apply to this branch, 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         branch is deleted
  27                                                 (valid on branch only)
  28
  29     Files which not inherit contents and changes from dependencies:
  30
  31         included        actual included branches, one per line
  32                                 topbloke branch name
  33
  34         pflags          flags that apply to this branch 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 Branches may be specified as
  49         [<qualifier>/...]<nickname-path-spec>
  50 where <qualifier>/ is one of
  51         [<email>]@[<domain.name>/
  52                 Only branches 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 branch
  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 branches are candidates
  71
  72 So overall, if the current branch is
  73         ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
  74 then all of the following can refer to the same branch
  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 branches with email address (or domain)
  89            matching current branch
  90         2. prefer branches with our own email address (or domain)
  91         3. other branches
  92 Within this there may be branches with multiple dates; prefer the most
  93 recent.