X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=topbloke.git;a=blobdiff_plain;f=FORMAT;h=ece197637ae6ba6db920fa28aa08e0ce095a69b4;hp=e9683bf2220e06ca0232b753e45c5c7deec76a8c;hb=c0f7fab5983a34c10790e39e7f48b546ca4011f7;hpb=94f53550123b9311a10d0e43ada446d4e3a9f144

diff --git a/FORMAT b/FORMAT
index e9683bf..ece1976 100644
--- 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