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