FORMAT: put deps etc. in base branch where we need them

[topbloke.git] / FORMAT

diff --git a/FORMAT b/FORMAT
index b755f249aac3d43a1dbcf6ad94c0a82d5fdf3f9f..593fede09b3d1822268c4b71970189e3c9002f8c 100644 (file)
--- a/FORMAT
+++ b/FORMAT
@@ -10,31 +10,52 @@ 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)
+       msg             patch "commit message"
+                       exist only in tip branch
 
        deps            direct dependencies, one per line
                        as either:
-                               topbloke patch name
-                               /refs/heads/<something>
-                       ("# not applicable" in bases)
+                               <topbloke patch name>
+                               - <ref name including refs/heads/>
+                       exist only in base branch
 
-       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         patch is deleted
-                                               (valid on tip only)
+       deleted         exists (but empty) if branch is deleted
+                       exist only in tip branch
 
-    Files which not inherit contents and changes from dependencies:
+       patch-          name of this topbloke patch (plus a newline)
+                       exists in base and tip, identical value
 
-       included        actual included deps, one per line
-                               format as for deps
+       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
 
-       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
+       [^+]*-          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
+
+       +*-             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
+
+    Any unknown metadata files not ending in "-" are fatal: tb
+    will refuse to operate on patches either of whose branches
+    have such files.
 
 
 <full-name> has the format:
@@ -46,7 +67,7 @@ eg
 NB only exactly that date format is allowed and timezone must be Z.
 
 Patches may be specified as
-       [<qualifier>/...]<nickname-path-spec>
+       [<qualifier>/...][<nickname-path-spec>]
 where <qualifier>/ is one of
        [<email>]@[<domain.name>/
                Only patches matching the specified email local part