chiark / gitweb /
before NEW THEORY
[topbloke.git] / 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