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