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
8 In-tree, there are metadata files in .topbloke
10 Files which are per-patch and do not inherit any contents
11 or changes from bases or dependencies:
13 msg patch "commit message"
14 exists only in tip branch
17 patch name of this topbloke patch (plus a newline)
18 exists in base and tip, identical value
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
24 deps direct dependencies, one per line
27 - <ref name including refs/heads/>
28 exists only in base branch
30 deleted exists (but empty) if patch is deleted
31 exists only in tip branch
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
38 [^+]*- another property that applies to this patch;
39 if not known to this version of topbloke then it
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
48 Files which inherit contents and changes from dependencies
49 have names starting with "+":
51 +included actual included deps, one per line
52 format as for deps, only includes topbloke patches
53 exists in tip and base branches
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+),
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
65 +*- another property that is inherited; it is also
67 - merge this file as text when merging
68 from tb dep into base, base into tip
71 Any unknown metadata files not ending in "-" are fatal: tb
72 will refuse to operate on patches either of whose branches
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)
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.
84 Patches may be specified with this grammar:
89 lump := datetime-spec ('/' email-spec) [abs-path]
90 | email-spec ('/' datetime-spec) [abs-path]
94 abs-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
103 path-tail := path-component
104 | path-component '/' rel-path
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
116 datetime-spec := nearby-date-spec
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.
125 date-pattern := [[ year '-' ] [month] '-' ] [mday]
126 year := <yyyy> | <yy>
127 month := <mm> | <m> | month-name
130 time-pattern := [ <hh> [ <mm> [ <ss> ]]]
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.
138 path-component := anything valid in a git ref name but no ',' or '/' or '@'
139 and not starting with digit
141 email-local-part := has the syntax of a valid git ref name
142 without any '@' or '/' or ','
145 Patch specification semantics:
147 * Calling context provides a scope, which restricts the set of
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.
154 1. prefer patches with email address (or domain)
155 matching current patch
156 2. prefer patches with our own email address (or domain)
158 Within this there may be patches with multiple dates; prefer the most
162 So overall, if the current patch is
164 ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
166 then all of the following can refer to the same patch
168 ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
178 ijackson@,reorg/sponge
179 ijackson@,/reorg/sponge
181 ijackson@chiark.greenend.org.uk,sponge
188 ijackson@/reorg/sponge
189 ijackson@/2012/reorg/sponge
190 ijackson@chiark.greenend.org.uk/reorg/sponge
193 Other notes re searching and patch identification:
196 ??? if using series defined by tips, how to stop other people stealing
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
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 ?