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                         exist only in tip branch
  15
  16         deps            direct dependencies, one per line
  17                         as either:
  18                                 <topbloke patch name>
  19                                 - <ref name including refs/heads/>
  20                         exist only in base branch
  21
  22         deleted         exists (but empty) if branch is deleted
  23                         exist only in tip branch
  24
  25         patch-          name of this topbloke patch (plus a newline)
  26                         exists in base and tip, identical value
  27
  28         topgit-         name of the topgit branch that this was
  29                         imported from and which we should merge from
  30                         (plus a newline)
  31                         exist only in base branch
  32
  33         [^+]*-          another property that applies to this patch;
  34                         if not known to this version of topbloke then it
  35                         is safe to:
  36                           - merge this file as text when merging
  37                             from base into base, or tip into tip,
  38                             and perhaps ask user to fix up conflicts
  39                             after warning if they feel expert
  40                           - throw away this file when merging from
  41                             from dep into base or base into tip
  42
  43     Files which inherit contents and changes from dependencies
  44     have names starting with "+":
  45
  46         +included       actual included deps, one per line
  47                         format as for deps
  48                         exists in tip and base branches
  49
  50         +*-             another property that is inherited; it is also
  51                         safe to:
  52                          - merge this file as text when merging
  53                            from tb dep into base, base into tip
  54                            or tip into tip
  55
  56     Any unknown metadata files not ending in "-" are fatal: tb
  57     will refuse to operate on patches either of whose branches
  58     have such files.
  59
  60
  61 <full-name> has the format:
  62         <email>@<domain.name>/<yyyy>-<mm>-<dd>T<hh><mm><ss>Z/<nickname-path>
  63 where nickname-path's first component must not start with a digit
  64 contain ~ or @  (: is not allowed in refs hence the squashing)
  65 eg
  66         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
  67 NB only exactly that date format is allowed and timezone must be Z.
  68
  69 Patches may be specified as
  70         [<qualifier>/...][<nickname-path-spec>]
  71 where <qualifier>/ is one of
  72         [<email>]@[<domain.name>/
  73                 Only patches matching the specified email local part
  74                 or domain name match
  75         [<date-spec>/]
  76                 A prefix of the ISO8601 date spec, stopping
  77                 just after a numeric component (or at the end)
  78         [<approx-date-containing-~>/]
  79                 Intepreted by date -d after ~s have been replaced by
  80                 spaces.  When we come to select, take the patch
  81                 nearest that date rather than the most recent
  82
  83
  84 <nickname-path-spec> may be
  85         <nickname-path>
  86         ./<nickname-new-leaf-component>
  87         ../<nickname-path-spec>
  88
  89 <date-spec> may be
  90         <approximate date spec containing at least one ~>
  91                 means all patches are candidates
  92
  93 So overall, if the current patch is
  94         ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
  95 then all of the following can refer to the same patch
  96         ./sponge
  97         ../reorg/sponge
  98         reorg/sponge
  99         2012/reorg/sponge
 100         2012/reorg/sponge
 101         2012/./sponge
 102         jan~/./sponge
 103         ijackson@/reorg/sponge
 104         ijackson@/2012/reorg/sponge
 105         ijackson@chiark.greenend.org.uk/reorg/sponge
 106         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
 107
 108 Search algorithm:
 109         1. prefer patches with email address (or domain)
 110            matching current patch
 111         2. prefer patches with our own email address (or domain)
 112         3. other patches
 113 Within this there may be patches with multiple dates; prefer the most
 114 recent.