chiark / gitweb /
FORMAT: wip new patch spec syntax and semantics
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 5 Feb 2012 16:39:04 +0000 (16:39 +0000)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 5 Feb 2012 16:39:04 +0000 (16:39 +0000)
FORMAT

diff --git a/FORMAT b/FORMAT
index 593fede..8729990 100644 (file)
--- 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