chiark / gitweb /
metadata merging plan
[topbloke.git] / FORMAT
diff --git a/FORMAT b/FORMAT
index 473946e32f37daec824e4176f2fd924d6a4c029f..7313ab8b2ea228857972ce978e2f5a17d43905f4 100644 (file)
--- a/FORMAT
+++ b/FORMAT
@@ -11,43 +11,52 @@ In-tree, there are metadata files in .topbloke
     or changes from bases or dependencies:
 
        msg             patch "commit message"
-                       ("# not applicable" in bases)
+                       exist only in tip branch
 
        deps            direct dependencies, one per line
                        as either:
                                <topbloke patch name>
                                .f <ref name including refs/heads/>
                                .tg <ref name not including refs/heads/>
-                       (empty in base branches)
+                       exist only in tip branch
 
        deleted         exists (but empty) if branch is deleted
-                       exist in tip only branch
+                       exist only in tip branch
 
        patch-          name of this topbloke patch (plus a newline)
-                       exists in base and tip
+                       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); exists in tip only
+                       (plus a newline)
+                       exist only in tip branch
 
        [^+]*-          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
+                           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
-                           base into tip or from dep into base
+                           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
+                       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 deps into bases or bases into tips
+                          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: