fix a few bugs in THEORY

[topbloke.git] / FORMAT

diff --git a/FORMAT b/FORMAT
index db703582187be88f9e0aee55a3f94bc2d4c24bd7..276051d5d1a046e54288956ac6f5d0dff0ed618a 100644 (file)
--- a/FORMAT
+++ b/FORMAT
@@ -11,24 +11,29 @@ In-tree, there are metadata files in .topbloke
     or changes from bases or dependencies:
 
        msg             patch "commit message"
-                       exist only in tip branch
+                       exists only in tip branch
+                       EDITED BY USER
+
+       patch           name of this topbloke patch (plus a newline)
+                       exists in base and tip, identical value
+
+       base            commit id of corresponding base B(C)
+                       exists only in tip branch
+                       this is how we tell tip from base commits
 
        deps            direct dependencies, one per line
                        as either:
                                <topbloke patch name>
                                - <ref name including refs/heads/>
-                       exist only in base branch
+                       exists only in base branch
 
-       deleted         exists (but empty) if branch is deleted
-                       exist only in tip branch
+       deleted         exists (but empty) if patch is deleted
+                       exists only in tip branch
 
-       patch-          name of this topbloke patch (plus a newline)
-                       exists in base and tip, identical value
-
-       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
+#TBD#  topgit-         name of the topgit branch that this was
+#TBD#                  imported from and which we should merge from
+#TBD#                  (plus a newline)
+#TBD#                  exists only in base branch
 
        [^+]*-          another property that applies to this patch;
                        if not known to this version of topbloke then it
@@ -44,9 +49,19 @@ In-tree, there are metadata files in .topbloke
     have names starting with "+":
 
        +included       actual included deps, one per line
-                       format as for deps
+                       format as for deps, only includes topbloke patches
                        exists in tip and base branches
 
+       +ends           list of ends E(C,Px+)
+                       format is one line per Px for which E(C,Px+) != { }
+                       the line contains the patch name Px plus
+                        the commit object names for E(C,Px+),
+                        separated by spaces
+                       in the case of tip commits, the commit's patch
+                        is not listed; for these implicitly E(C,Px+) = { C }
+                       always exists in tip and base branches, perhaps as
+                        an empty file
+
        +*-             another property that is inherited; it is also
                        safe to:
                         - merge this file as text when merging
@@ -186,4 +201,5 @@ head overlappingness by email address pairs, stops other people
 extending your series
 
 series name in each patch ?  some patches marked as definitely series tip ?
-
+some bases marked as definitively series base ?
+"insert after this patch, rewrite all deps everywhere" option ?