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                         exists only in tip branch
  15                         EDITED BY USER
  16
  17         patch           name of this topbloke patch (plus a newline)
  18                         exists in base and tip, identical value
  19
  20         base            commit id of corresponding base B(C)
  21                         exists only in tip branch
  22                         this is how we tell tip from base commits
  23
  24         deps            direct dependencies, one per line
  25                         as either:
  26                                 <topbloke patch name>
  27                                 - <ref name including refs/heads/>
  28                         exists only in base branch
  29
  30         deleted         exists (but empty) if patch is deleted
  31                         exists only in tip branch
  32
  33 #TBD#   topgit-         name of the topgit branch that this was
  34 #TBD#                   imported from and which we should merge from
  35 #TBD#                   (plus a newline)
  36 #TBD#                   exists only in base branch
  37
  38         [^+]*-          another property that applies to this patch;
  39                         if not known to this version of topbloke then it
  40                         is safe to:
  41                           - merge this file as text when merging
  42                             from base into base, or tip into tip,
  43                             and perhaps ask user to fix up conflicts
  44                             after warning if they feel expert
  45                           - throw away this file when merging from
  46                             from dep into base or base into tip
  47
  48     Files which inherit contents and changes from dependencies
  49     have names starting with "+":
  50
  51         +included       actual included deps, one per line
  52                         format as for deps, only includes topbloke patches
  53                         exists in tip and base branches
  54
  55         +ends           list of ends E(C,Px+)
  56                         format is one line per Px for which E(C,Px+) != { }
  57                         the line contains the patch name Px plus
  58                          the commit object names for E(C,Px+),
  59                          separated by spaces
  60                         in the case of tip commits, the commit's patch
  61                          is not listed; for these implicitly E(C,Px+) = { C }
  62                         always exists in tip and base branches, perhaps as
  63                          an empty file
  64
  65         +*-             another property that is inherited; it is also
  66                         safe to:
  67                          - merge this file as text when merging
  68                            from tb dep into base, base into tip
  69                            or tip into tip
  70
  71     Any unknown metadata files not ending in "-" are fatal: tb
  72     will refuse to operate on patches either of whose branches
  73     have such files.
  74
  75
  76 <full-name> has the format:
  77         <email>@<domain.name>/<yyyy>-<mm>-<dd>T<hh><mm><ss>Z/<nickname-path>
  78 where none of nickname-path's components may start with a digit
  79 or contain ~ or @  (: is not allowed in refs hence the squashing after T)
  80 eg
  81         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
  82 NB only exactly that date format is allowed and timezone must be Z.
  83
  84 Patches may be specified with this grammar:
  85
  86    spec := lump
  87          | lump ',' spec
  88
  89    lump := datetime-spec ('/' email-spec) [abs-path]
  90          | email-spec ('/' datetime-spec) [abs-path]
  91          | '/' abs-path
  92          | rel-path
  93
  94    abs-path = '/' path-tail
  95
  96    rel-path := path-tail
  97         # Interpretation depends on current patch nickname path:
  98         # each path-component replaces one path-component from the
  99         # current path, starting from the rhs, so that the specified
 100         # nickname path has the same number of components.
 101         # Matching patches are only those with an identical nickname path
 102
 103    path-tail := path-component
 104               | path-component '/' rel-path
 105
 106    email-spec := [email-local-part] '@' [domain-name]
 107         # If email-local-part is specified, matches only identical ones.
 108         # If domain-name is specified, matches only identical ones.
 109         # If no email-spec is specified at all (not even an empty one)
 110         # then we search as follows:
 111         #   1. Are there any patches with the same email address as
 112         #      our current patch, which match the rest of the spec ?
 113         #      If so, only those are considered.
 114         #   2. Otherwise, are there any patches
 115
 116    datetime-spec := nearby-date-spec
 117                   | datetime-pattern
 118
 119    datetime-pattern := date-pattern
 120                     | [date-pattern] 'T' time-pattern
 121         # Matching patches are those which match on all specified
 122         # components.  The chosen patch is the most recent one
 123         # which matches everything in the spec.
 124
 125    date-pattern := [[ year '-' ] [month] '-' ] [mday]
 126    year := <yyyy> | <yy>
 127    month := <mm> | <m> | month-name
 128    mday := <dd> | <d>
 129
 130    time-pattern := [ <hh> [ <mm> [ <ss> ]]]
 131
 132    nearby-date-spec := some string containing '~'
 133         # Each '~' is replaced with ' ' and then the result is
 134         # fed to date -d.  Of the matching patches (ie with any date)
 135         # the one matching all the rest of the spec but with
 136         # the date closest to that specified is chosen.
 137
 138    path-component := anything valid in a git ref name but no ',' or '/' or '@'
 139                      and not starting with digit
 140
 141    email-local-part := has the syntax of a valid git ref name
 142                        without any '@' or '/' or ','
 143
 144
 145 Patch specification semantics:
 146
 147  * Calling context provides a scope, which restricts the set of
 148    possible patches.
 149  * If no email address in spec, look for patches in that set whose email
 150    address is the same as the user's email address.
 151  * ... ???
 152
 153 Search algorithm:
 154         1. prefer patches with email address (or domain)
 155            matching current patch
 156         2. prefer patches with our own email address (or domain)
 157         3. other patches
 158 Within this there may be patches with multiple dates; prefer the most
 159 recent.
 160
 161
 162 So overall, if the current patch is
 163
 164         ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
 165
 166 then all of the following can refer to the same patch
 167
 168         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
 169
 170         sponge
 171         reorg/sponge
 172         /reorg/sponge
 173
 174         sponge,2012
 175         2012,/reorg/sponge
 176         ijackson@,sponge
 177         sponge,ijackson@
 178         ijackson@,reorg/sponge
 179         ijackson@,/reorg/sponge
 180         jan~,sponge
 181         ijackson@chiark.greenend.org.uk,sponge
 182
 183         sponge
 184         reorg/sponge
 185         /reorg/sponge
 186         2012/reorg/sponge
 187         jan~/reorg/sponge
 188         ijackson@/reorg/sponge
 189         ijackson@/2012/reorg/sponge
 190         ijackson@chiark.greenend.org.uk/reorg/sponge
 191
 192
 193 Other notes re searching and patch identification:
 194
 195
 196 ??? if using series defined by tips, how to stop other people stealing
 197  our tips  -
 198
 199 have a way to limit refs pull by email address have a way to limit
 200 head overlappingness by email address pairs, stops other people
 201 extending your series
 202
 203 series name in each patch ?  some patches marked as definitely series tip ?
 204 some bases marked as definitively series base ?
 205 "insert after this patch, rewrite all deps everywhere" option ?