nickname is optional in patch specs

[topbloke.git] / FORMAT

diff --git a/FORMAT b/FORMAT
index 5c22cc6f9104e74027f89442c22b0380c52ececd..e411d3875fa978e7908561a3f02ff23bce2ccd4b 100644 (file)
--- a/FORMAT
+++ b/FORMAT
@@ -1,4 +1,4 @@
-Topbloke branch is:
+Topbloke patch is:
        - branch in refs/topbloke-tips/<full-name>
                contains the working version, fast-forwarding
        - branch in refs/topbloke-bases/<full-name>
@@ -7,22 +7,34 @@ Topbloke branch is:
 
 In-tree, there are metadata files in .topbloke
 
+    Files which are per-patch 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
                        as either:
-                               topbloke branch name
+                               topbloke patch name
                                /refs/heads/<something>
+                       ("# not applicable" in bases)
 
-       included        actual included branches, one per line
-                               topbloke branch name
-
-       flags           flags that apply to this branch, one per line
-                        unknown flags starting with [a-z] are ok;
+       flags           flags that apply to this patch, one per line
+                       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
+                               Deleted         patch is deleted
+                                               (valid on tip only)
+
+    Files which not inherit contents and changes from dependencies:
+
+       included        actual included deps, one per line
+                               format as for deps
 
-       .gitattributes  Sets the attributes
+       pflags          flags that apply to this patch 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:
@@ -33,18 +45,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
-       [<qualifier>/...]<nickname-path-spec>
+Patches may be specified as
+       [<qualifier>/...][<nickname-path-spec>]
 where <qualifier>/ is one of
        [<email>]@[<domain.name>/
-               Only branches matching the specified email local part
+               Only patches 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
+               spaces.  When we come to select, take the patch
                nearest that date rather than the most recent
 
 
@@ -55,11 +67,11 @@ where <qualifier>/ is one of
 
 <date-spec> may be
        <approximate date spec containing at least one ~>
-               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
@@ -73,9 +85,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.