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
 
 
 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"
        msg             brach "commit message"

+                       ("# not applicable" in bases)

 
        deps            direct dependencies, one per line
 
        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
 
        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
                         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:
 
 
 <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
 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>
 
 <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 ~>
 
 <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
 
 So overall, if the current branch is
        ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding