From 3f3b1381e95ef73bb179b0b62703f116fec18e5a Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 5 Feb 2012 16:39:04 +0000
Subject: [PATCH] FORMAT: wip new patch spec syntax and semantics

---
 FORMAT | 130 ++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 91 insertions(+), 39 deletions(-)

diff --git a/FORMAT b/FORMAT
index 593fede..8729990 100644
--- a/FORMAT
+++ b/FORMAT
@@ -60,50 +60,71 @@ In-tree, there are metadata files in .topbloke
 
 <full-name> has the format:
 	<email>@<domain.name>/<yyyy>-<mm>-<dd>T<hh><mm><ss>Z/<nickname-path>
-where nickname-path's first component must not start with a digit 
-contain ~ or @  (: is not allowed in refs hence the squashing)
+where none of nickname-path's components may start with a digit
+or contain ~ or @  (: is not allowed in refs hence the squashing after T)
 eg
 	ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
 NB only exactly that date format is allowed and timezone must be Z.
 
-Patches may be specified as
-	[<qualifier>/...][<nickname-path-spec>]
-where <qualifier>/ is one of
-	[<email>]@[<domain.name>/
-		Only patches 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 patch
-		nearest that date rather than the most recent
-
-
-<nickname-path-spec> may be
-	<nickname-path>
-	./<nickname-new-leaf-component>
-	../<nickname-path-spec>
-
-<date-spec> may be
-	<approximate date spec containing at least one ~>
-		means all patches are candidates
+Patches may be specified with this grammar:
 
-So overall, if the current patch is
-	ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
-then all of the following can refer to the same patch
-	./sponge
-	../reorg/sponge
-	reorg/sponge
-	2012/reorg/sponge
-	2012/reorg/sponge
-	2012/./sponge
-	jan~/./sponge
-	ijackson@/reorg/sponge
-	ijackson@/2012/reorg/sponge
-	ijackson@chiark.greenend.org.uk/reorg/sponge
-	ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
+   spec := lump
+	 | lump ',' spec
+
+   lump := datetime-spec ('/' email-spec) [abs-path]
+	 | email-spec ('/' datetime-spec) [abs-path]
+	 | '/' abs-path
+	 | rel-path
+
+   abs-path = '/' path-tail
+
+   rel-path := path-tail
+	# Interpretation depends on current patch nickname path:
+	# each path-component replaces one path-component from the
+	# current path, starting from the rhs, so that the specified
+	# nickname path has the same number of components.
+	# Matching patches are only those with an identical nickname path
+
+   path-tail := path-component
+	      | path-component '/' rel-path
+
+   email-spec := [email-local-part] '@' [domain-name]
+	# If email-local-part is specified, matches only identical ones.
+	# If domain-name is specified, matches only identical ones.
+	# If no email-spec is specified at all (not even an empty one)
+	# then we search as follows:
+	#   1. Are there any patches with the same email address as
+	#      our current patch, which match the rest of the spec ?  
+	#      If so, only those are considered.
+	#   2. Otherwise, are there any patches 
+
+   datetime-spec := nearby-date-spec
+                  | datetime-pattern
+
+   datetime-pattern := date-pattern
+                    | [date-pattern] 'T' time-pattern
+	# Matching patches are those which match on all specified
+	# components.  The chosen patch is the most recent one
+	# which matches everything in the spec.
+
+   date-pattern := [[ year '-' ] [month] '-' ] [mday]
+   year := <yyyy> | <yy>
+   month := <mm> | <m> | month-name
+   mday := <dd> | <d>
+
+   time-pattern := [ <hh> [ <mm> [ <ss> ]]]
+
+   nearby-date-spec := some string containing '~'
+	# Each '~' is replaced with ' ' and then the result is
+	# fed to date -d.  Of the matching patches (ie with any date)
+	# the one matching all the rest of the spec but with
+	# the date closest to that specified is chosen.
+
+   path-component := anything valid in a git ref name but no ',' or '/' or '@'
+		     and not starting with digit
+
+   email-local-part := has the syntax of a valid git ref name 
+                       without any '@' or '/' or ','
 
 Search algorithm:
 	1. prefer patches with email address (or domain)
@@ -112,3 +133,34 @@ Search algorithm:
 	3. other patches
 Within this there may be patches with multiple dates; prefer the most
 recent.
+
+
+So overall, if the current patch is
+
+	ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
+
+then all of the following can refer to the same patch
+
+	ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
+
+	sponge
+	reorg/sponge
+	/reorg/sponge
+
+	sponge,2012
+	2012,/reorg/sponge
+	ijackson@,sponge
+	sponge,ijackson@
+	ijackson@,reorg/sponge
+	ijackson@,/reorg/sponge
+	jan~,sponge
+	ijackson@chiark.greenend.org.uk,sponge
+
+	sponge
+	reorg/sponge
+	/reorg/sponge
+	2012/reorg/sponge
+	jan~/reorg/sponge
+	ijackson@/reorg/sponge
+	ijackson@/2012/reorg/sponge
+	ijackson@chiark.greenend.org.uk/reorg/sponge
-- 
2.30.2