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