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