chiark / gitweb /
wip tb-list
[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             brach "commit message"
14                         ("# not applicable" in bases)
15
16         deps            direct dependencies, one per line
17                         as either:
18                                 topbloke patch name
19                                 /refs/heads/<something>
20                         ("# not applicable" in bases)
21
22         flags           flags that apply to this patch, one per line
23                         base has its own, perhaps different, set of flags;
24                          Unknown flags starting with [a-z] are ok;
25                          otherwise fatal.  Currently defined flags:
26                                 Deleted         patch is deleted
27                                                 (valid on tip only)
28
29     Files which not inherit contents and changes from dependencies:
30
31         included        actual included deps, one per line
32                                 format as for deps
33
34         pflags          flags that apply to this patch and all its
35                         dependencies (ie, flags that propagate)
36                          Unknown flags starting with [a-z] are ok;
37                          otherwise fatal.  No currently defined flags
38
39
40 <full-name> has the format:
41         <email>@<domain.name>/<yyyy>-<mm>-<dd>T<hh><mm><ss>Z/<nickname-path>
42 where nickname-path's first component must not start with a digit 
43 contain ~ or @  (: is not allowed in refs hence the squashing)
44 eg
45         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
46 NB only exactly that date format is allowed and timezone must be Z.
47
48 Patches may be specified as
49         [<qualifier>/...][<nickname-path-spec>]
50 where <qualifier>/ is one of
51         [<email>]@[<domain.name>/
52                 Only patches matching the specified email local part
53                 or domain name match
54         [<date-spec>/]
55                 A prefix of the ISO8601 date spec, stopping
56                 just after a numeric component (or at the end)
57         [<approx-date-containing-~>/]
58                 Intepreted by date -d after ~s have been replaced by
59                 spaces.  When we come to select, take the patch
60                 nearest that date rather than the most recent
61
62
63 <nickname-path-spec> may be
64         <nickname-path>
65         ./<nickname-new-leaf-component>
66         ../<nickname-path-spec>
67
68 <date-spec> may be
69         <approximate date spec containing at least one ~>
70                 means all patches are candidates
71
72 So overall, if the current patch is
73         ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
74 then all of the following can refer to the same patch
75         ./sponge
76         ../reorg/sponge
77         reorg/sponge
78         2012/reorg/sponge
79         2012/reorg/sponge
80         2012/./sponge
81         jan~/./sponge
82         ijackson@/reorg/sponge
83         ijackson@/2012/reorg/sponge
84         ijackson@chiark.greenend.org.uk/reorg/sponge
85         ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
86
87 Search algorithm:
88         1. prefer patches with email address (or domain)
89            matching current patch
90         2. prefer patches with our own email address (or domain)
91         3. other patches
92 Within this there may be patches with multiple dates; prefer the most
93 recent.