X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=topbloke.git;a=blobdiff_plain;f=FORMAT;h=db703582187be88f9e0aee55a3f94bc2d4c24bd7;hp=1b823f05a1c9f8fe95e9ca412d666163f0e09969;hb=5ae399ddff45b6edb446ee5d9b779fb91985e439;hpb=494c30db6e5fd21d19e8dfc9a10fd37fe46529d0 diff --git a/FORMAT b/FORMAT index 1b823f0..db70358 100644 --- a/FORMAT +++ b/FORMAT @@ -11,89 +11,179 @@ 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: - .f - .tg - (empty in base branches) + - + exist only in base branch - props properties that apply to this patch, one per line - in the format "[ ]" (exactly one - space) where value can contain spaces and - a missing value is distinct from a missing property - but value if present must be nonempty - base has its own, perhaps different, set of props; - Unknown props starting with [a-z] are ok; - otherwise fatal. Currently defined props: - patch topbloke patch name (in tip and base) - topgit this is a topgit import (in tip and base) - Deleted patch is deleted (in tip only, no value) + deleted exists (but empty) if branch is deleted + exist only in tip branch - Files which not inherit contents and changes from dependencies: + patch- name of this topbloke patch (plus a newline) + exists in base and tip, identical value - included actual included deps, one per line - format as for deps + 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 - pprops properties that apply to this patch and all its - dependencies (ie, properties that propagate) - Unknown props starting with [a-z] are ok; - otherwise fatal. No currently defined props. + [^+]*- 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, + and perhaps ask user to fix up conflicts + after warning if they feel expert + - throw away this file when merging from + 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 + 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 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. has the format: @/--
TZ/ -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 - [/...][] -where / is one of - []@[/ - Only patches matching the specified email local part - or domain name match - [/] - A prefix of the ISO8601 date spec, stopping - just after a numeric component (or at the end) - [/] - 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 - - - may be - - ./ - ../ - - may be - - means all patches are candidates +Patches may be specified with this grammar: + + 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 := | + month := | | month-name + mday :=
| + + time-pattern := [ [ [ ]]] + + 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 ',' + + +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 + 2. prefer patches with our own email address (or domain) + 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 - ./sponge - ../reorg/sponge + + 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 - 2012/reorg/sponge - 2012/./sponge - jan~/./sponge + jan~/reorg/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 -Search algorithm: - 1. prefer patches with email address (or domain) - matching current patch - 2. prefer patches with our own email address (or domain) - 3. other patches -Within this there may be patches with multiple dates; prefer the most -recent. + +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 ? +