X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=FORMAT;h=593fede09b3d1822268c4b71970189e3c9002f8c;hb=3e8d721402b8e907a2658ef86ce9c05756f85c56;hp=258e073205cb39874e446435c7eceb06fd19902e;hpb=6e11e84991fb6d32695f9bcce6bd29f00f704111;p=topbloke.git diff --git a/FORMAT b/FORMAT index 258e073..593fede 100644 --- a/FORMAT +++ b/FORMAT @@ -1,4 +1,4 @@ -Topbloke branch is: +Topbloke patch is: - branch in refs/topbloke-tips/ contains the working version, fast-forwarding - branch in refs/topbloke-bases/ @@ -7,20 +7,55 @@ Topbloke branch is: In-tree, there are metadata files in .topbloke - msg brach "commit message" + Files which are per-patch and do not inherit any contents + or changes from bases or dependencies: + + msg patch "commit message" + exist only in tip branch deps direct dependencies, one per line as either: - topbloke branch name - /refs/heads/ + + - + exist only in base branch + + deleted exists (but empty) if branch is deleted + exist only in tip branch + + patch- name of this topbloke patch (plus a newline) + exists in base and tip, identical value + + topgit- name of the topgit branch that this was + imported from and which we should merge from + (plus a newline) + exist only in base branch + + [^+]*- another property that applies to this patch; + if not known to this version of topbloke then it + is safe to: + - merge this file as text when merging + from base into base, or tip into tip, + and perhaps ask user to fix up conflicts + after warning if they feel expert + - throw away this file when merging from + from dep into base or base into tip + + Files which inherit contents and changes from dependencies + have names starting with "+": + + +included actual included deps, one per line + format as for deps + exists in tip and base branches - included actual included branches, one per line - topbloke branch name + +*- another property that is inherited; it is also + safe to: + - merge this file as text when merging + from tb dep into base, base into tip + or tip into tip - flags flags that apply to this branch, one per line - unknown flags starting with [a-z] are ok; - otherwise fatal. Currently defined flags: - Deleted branch is deleted + Any unknown metadata files not ending in "-" are fatal: tb + will refuse to operate on patches either of whose branches + have such files. has the format: @@ -31,18 +66,18 @@ eg ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge NB only exactly that date format is allowed and timezone must be Z. -Branches may be specified as - [/...] +Patches may be specified as + [/...][] where / is one of []@[/ - Only branches matching the specified email local part + Only patches matching the specified email local part or domain name match [/] A prefix of the ISO8601 date spec, stopping just after a numeric component (or at the end) [/] Intepreted by date -d after ~s have been replaced by - spaces. When we come to select, take the branch + spaces. When we come to select, take the patch nearest that date rather than the most recent @@ -53,11 +88,11 @@ where / is one of may be - means all branches are candidates + means all patches are candidates -So overall, if the current branch is +So overall, if the current patch is ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding -then all of the following can refer to the same branch +then all of the following can refer to the same patch ./sponge ../reorg/sponge reorg/sponge @@ -71,9 +106,9 @@ then all of the following can refer to the same branch ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge Search algorithm: - 1. prefer branches with email address (or domain) - matching current branch - 2. prefer branches with our own email address (or domain) - 3. other branches -Within this there may be branches with multiple dates; prefer the most + 1. prefer patches with email address (or domain) + matching current patch + 2. prefer patches with our own email address (or domain) + 3. other patches +Within this there may be patches with multiple dates; prefer the most recent.