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 none of nickname-path's components may start with a digit
  64 or contain ~ or @  (: is not allowed in refs hence the squashing after T)
  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 with this grammar:
  70
  71    spec := lump
  72          | lump ',' spec
  73
  74    lump := datetime-spec ('/' email-spec) [abs-path]
  75          | email-spec ('/' datetime-spec) [abs-path]
  76          | '/' abs-path
  77          | rel-path
  78
  79    abs-path = '/' path-tail
  80
  81    rel-path := path-tail
  82         # Interpretation depends on current patch nickname path:
  83         # each path-component replaces one path-component from the
  84         # current path, starting from the rhs, so that the specified
  85         # nickname path has the same number of components.
  86         # Matching patches are only those with an identical nickname path
  87
  88    path-tail := path-component
  89               | path-component '/' rel-path
  90
  91    email-spec := [email-local-part] '@' [domain-name]
  92         # If email-local-part is specified, matches only identical ones.
  93         # If domain-name is specified, matches only identical ones.
  94         # If no email-spec is specified at all (not even an empty one)
  95         # then we search as follows:
  96         #   1. Are there any patches with the same email address as
  97         #      our current patch, which match the rest of the spec ?
  98         #      If so, only those are considered.
  99         #   2. Otherwise, are there any patches
 100
 101    datetime-spec := nearby-date-spec
 102                   | datetime-pattern
 103
 104    datetime-pattern := date-pattern
 105                     | [date-pattern] 'T' time-pattern
 106         # Matching patches are those which match on all specified
 107         # components.  The chosen patch is the most recent one
 108         # which matches everything in the spec.
 109
 110    date-pattern := [[ year '-' ] [month] '-' ] [mday]
 111    year := <yyyy> | <yy>
 112    month := <mm> | <m> | month-name
 113    mday := <dd> | <d>
 114
 115    time-pattern := [ <hh> [ <mm> [ <ss> ]]]
 116
 117    nearby-date-spec := some string containing '~'
 118         # Each '~' is replaced with ' ' and then the result is
 119         # fed to date -d.  Of the matching patches (ie with any date)
 120         # the one matching all the rest of the spec but with
 121         # the date closest to that specified is chosen.
 122
 123    path-component := anything valid in a git ref name but no ',' or '/' or '@'
 124                      and not starting with digit
 125
 126    email-local-part := has the syntax of a valid git ref name
 127                        without any '@' or '/' or ','
 128
 129
 130 Patch specification semantics:
 131
 132  * Calling context provides a scope, which restricts the set of
 133    possible patches.
 134  * If no email address in spec, look for patches in that set whose email
 135    address is the same as the user's email address.
 136  * ... ???
 137
 138 Search algorithm:
 139         1. prefer patches with email address (or domain)
 140            matching current patch
 141         2. prefer patches with our own email address (or domain)
 142         3. other patches
 143 Within this there may be patches with multiple dates; prefer the most
 144 recent.
 145
 146
 147 So overall, if the current patch is
 148
 149         ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
 150
 151 then all of the following can refer to the same patch
 152
 153         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
 154
 155         sponge
 156         reorg/sponge
 157         /reorg/sponge
 158
 159         sponge,2012
 160         2012,/reorg/sponge
 161         ijackson@,sponge
 162         sponge,ijackson@
 163         ijackson@,reorg/sponge
 164         ijackson@,/reorg/sponge
 165         jan~,sponge
 166         ijackson@chiark.greenend.org.uk,sponge
 167
 168         sponge
 169         reorg/sponge
 170         /reorg/sponge
 171         2012/reorg/sponge
 172         jan~/reorg/sponge
 173         ijackson@/reorg/sponge
 174         ijackson@/2012/reorg/sponge
 175         ijackson@chiark.greenend.org.uk/reorg/sponge
 176
 177
 178 Other notes re searching and patch identification:
 179
 180
 181 ??? if using series defined by tips, how to stop other people stealing
 182  our tips  -
 183
 184 have a way to limit refs pull by email address have a way to limit
 185 head overlappingness by email address pairs, stops other people
 186 extending your series
 187
 188 series name in each patch ?  some patches marked as definitely series tip ?
 189