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         msg             brach "commit message"
  11
  12         deps            direct dependencies, one per line
  13
  14         included        actual included branches, one per line
  15
  16         flags           flags that apply to this branch, one per line
  17                          unknown flags starting with [a-z] are ok;
  18                          otherwise fatal.  Currently defined flags:
  19                                 Deleted         branch is deleted
  20
  21
  22 <full-name> has the format:
  23         <email>@<domain.name>/<yyyy>-<mm>-<dd>T<hh><mm><ss>Z/<nickname-path>
  24 where nickname-path's first component must not start with a digit
  25 contain ~ or @  (: is not allowed in refs hence the squashing)
  26 eg
  27         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
  28 NB only exactly that date format is allowed and timezone must be Z.
  29
  30 Branches may be specified as
  31         [<email>@[<domain.name>/][<date-spec>/]<nickname-path-spec>
  32
  33 <nickname-path-spec> may be
  34         <nickname-path>
  35         ./<nickname-new-leaf-component>
  36         ../<nickname-path-spec>
  37
  38 <date-spec> may be
  39         <approximate date spec containing at least one ~>
  40                 means all branches are candidates; when we come
  41                 to select, take the branch nearest that date rather than
  42                 the most recent; the date spec is intepreted by date -d
  43                 after ~s have been replaced by spaces
  44         A prefix of the ISO8601 date spec, stopping just after a
  45                 numeric component (or at the end)
  46
  47 So overall, if the current branch is
  48         ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
  49 then all of the following can refer to the same branch
  50         ./sponge
  51         ../reorg/sponge
  52         reorg/sponge
  53         2012/reorg/sponge
  54         2012/reorg/sponge
  55         2012/./sponge
  56         jan~/./sponge
  57         ijackson@/reorg/sponge
  58         ijackson@/2012/reorg/sponge
  59         ijackson@chiark.greenend.org.uk/reorg/sponge
  60         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
  61
  62 Search algorithm:
  63         1. prefer branches with email address (or domain)
  64            matching current branch
  65         2. prefer branches with our own email address (or domain)
  66         3. other branches
  67 Within this there may be branches with multiple dates; prefer the most
  68 recent.