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 exist only in tip branch
16 deps direct dependencies, one per line
19 - <ref name including refs/heads/>
20 exist only in base branch
22 deleted exists (but empty) if branch is deleted
23 exist only in tip branch
25 patch- name of this topbloke patch (plus a newline)
26 exists in base and tip, identical value
28 topgit- name of the topgit branch that this was
29 imported from and which we should merge from
31 exist only in base branch
33 [^+]*- another property that applies to this patch;
34 if not known to this version of topbloke then it
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
43 Files which inherit contents and changes from dependencies
44 have names starting with "+":
46 +included actual included deps, one per line
48 exists in tip and base branches
50 +*- another property that is inherited; it is also
52 - merge this file as text when merging
53 from tb dep into base, base into tip
56 Any unknown metadata files not ending in "-" are fatal: tb
57 will refuse to operate on patches either of whose branches
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)
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.
69 Patches may be specified with this grammar:
74 lump := datetime-spec ('/' email-spec) [abs-path]
75 | email-spec ('/' datetime-spec) [abs-path]
79 abs-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
88 path-tail := path-component
89 | path-component '/' rel-path
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
101 datetime-spec := nearby-date-spec
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.
110 date-pattern := [[ year '-' ] [month] '-' ] [mday]
111 year := <yyyy> | <yy>
112 month := <mm> | <m> | month-name
115 time-pattern := [ <hh> [ <mm> [ <ss> ]]]
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.
123 path-component := anything valid in a git ref name but no ',' or '/' or '@'
124 and not starting with digit
126 email-local-part := has the syntax of a valid git ref name
127 without any '@' or '/' or ','
130 Patch specification semantics:
132 * Calling context provides a scope, which restricts the set of
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.
139 1. prefer patches with email address (or domain)
140 matching current patch
141 2. prefer patches with our own email address (or domain)
143 Within this there may be patches with multiple dates; prefer the most
147 So overall, if the current patch is
149 ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
151 then all of the following can refer to the same patch
153 ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
163 ijackson@,reorg/sponge
164 ijackson@,/reorg/sponge
166 ijackson@chiark.greenend.org.uk,sponge
173 ijackson@/reorg/sponge
174 ijackson@/2012/reorg/sponge
175 ijackson@chiark.greenend.org.uk/reorg/sponge
178 Other notes re searching and patch identification:
181 ??? if using series defined by tips, how to stop other people stealing
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
188 series name in each patch ? some patches marked as definitely series tip ?