X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=FORMAT;h=42f7fa445b41b9a47a06af2644fea0b61b1403a5;hb=2799df8533bddff6feeee7c1b9d31cc6583e04f9;hp=8729990dc79a75ccd5119d35afc4b5d4451767b9;hpb=3f3b1381e95ef73bb179b0b62703f116fec18e5a;p=topbloke.git

diff --git a/FORMAT b/FORMAT
index 8729990..42f7fa4 100644
--- 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
-
-	deleted		exists (but empty) if branch is deleted
-			exist only in tip branch
+			exists only in base branch
 
-	patch-		name of this topbloke patch (plus a newline)
-			exists in base and tip, identical value
+	deleted		exists (but empty) if patch is deleted
+			exists only in tip branch
 
 	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
+			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
@@ -126,6 +141,15 @@ Patches may be specified with this grammar:
    email-local-part := has the syntax of a valid git ref name 
                        without any '@' or '/' or ','
 
+
+Patch specification semantics:
+
+ * Calling context provides a scope, which restricts the set of
+   possible patches.
+ * If no email address in spec, look for patches in that set whose email
+   address is the same as the user's email address.
+ * ... ???
+
 Search algorithm:
 	1. prefer patches with email address (or domain)
 	   matching current patch
@@ -164,3 +188,18 @@ then all of the following can refer to the same patch
 	ijackson@/reorg/sponge
 	ijackson@/2012/reorg/sponge
 	ijackson@chiark.greenend.org.uk/reorg/sponge
+
+
+Other notes re searching and patch identification:
+
+
+??? if using series defined by tips, how to stop other people stealing
+ our tips  -  
+
+have a way to limit refs pull by email address have a way to limit
+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 ?