wip tb-create

[topbloke.git] / FORMAT

diff --git a/FORMAT b/FORMAT
index e9683bf2220e06ca0232b753e45c5c7deec76a8c..ece197637ae6ba6db920fa28aa08e0ce095a69b4 100644 (file)
--- a/FORMAT
+++ b/FORMAT
@@ -7,16 +7,34 @@ Topbloke branch is:
 
 In-tree, there are metadata files in .topbloke
 
+    Files which are per-branch and do not inherit any contents
+    or changes from bases or dependencies:
+
        msg             brach "commit message"
+                       ("# not applicable" in bases)
 
        deps            direct dependencies, one per line
-
-       included        actual included branches, one per line
+                       as either:
+                               topbloke branch name
+                               /refs/heads/<something>
+                       ("# not applicable" in bases)
 
        flags           flags that apply to this branch, one per line
-                        unknown flags starting with [a-z] are ok;
+                       base has its own, perhaps different, set of flags;
+                        Unknown flags starting with [a-z] are ok;
                         otherwise fatal.  Currently defined flags:
                                Deleted         branch is deleted
+                                               (valid on branch only)
+
+    Files which not inherit contents and changes from dependencies:
+
+       included        actual included branches, one per line
+                               topbloke branch name
+
+       pflags          flags that apply to this branch and all its
+                       dependencies (ie, flags that propagate)
+                        Unknown flags starting with [a-z] are ok;
+                        otherwise fatal.  No currently defined flags
 
 
 <full-name> has the format:
@@ -28,7 +46,19 @@ eg
 NB only exactly that date format is allowed and timezone must be Z.
 
 Branches may be specified as
-       [<email>@[<domain.name>/][<date-spec>/]<nickname-path-spec>
+       [<qualifier>/...]<nickname-path-spec>
+where <qualifier>/ is one of
+       [<email>]@[<domain.name>/
+               Only branches matching the specified email local part
+               or domain name match
+       [<date-spec>/]
+               A prefix of the ISO8601 date spec, stopping
+               just after a numeric component (or at the end)
+       [<approx-date-containing-~>/]
+               Intepreted by date -d after ~s have been replaced by
+               spaces.  When we come to select, take the branch
+               nearest that date rather than the most recent
+
 
 <nickname-path-spec> may be
        <nickname-path>
@@ -37,12 +67,7 @@ Branches may be specified as
 
 <date-spec> may be
        <approximate date spec containing at least one ~>
-               means all branches are candidates; when we come
-               to select, take the branch nearest that date rather than
-               the most recent; the date spec is intepreted by date -d
-               after ~s have been replaced by spaces
-       A prefix of the ISO8601 date spec, stopping just after a
-               numeric component (or at the end)
+               means all branches are candidates
 
 So overall, if the current branch is
        ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding