From 94f53550123b9311a10d0e43ada446d4e3a9f144 Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Fri, 20 Jan 2012 23:21:02 +0000
Subject: [PATCH] wip; branch name format

---
 DESIGN |  1 -
 FORMAT | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 FORMAT

diff --git a/DESIGN b/DESIGN
index f03febb..bac524c 100644
--- a/DESIGN
+++ b/DESIGN
@@ -144,7 +144,6 @@ Branch removal:
 Branch naming:
  needs to be globally unique
  so put email address in it
- also "tree" or "context" name, found automatically
 tg operations search for applicable branches
 safe charset for branch names
   . - / 0-9 a-z
diff --git a/FORMAT b/FORMAT
new file mode 100644
index 0000000..e9683bf
--- /dev/null
+++ b/FORMAT
@@ -0,0 +1,68 @@
+Topbloke branch is:
+	- branch in refs/topbloke-tips/<full-name>
+		contains the working version, fast-forwarding
+	- branch in refs/topbloke-bases/<full-name>
+		contains the base version, being the pulling
+		merge of all the bases
+
+In-tree, there are metadata files in .topbloke
+
+	msg		brach "commit message"
+
+	deps		direct dependencies, one per line
+
+	included	actual included branches, one per line
+
+	flags		flags that apply to this branch, one per line
+			 unknown flags starting with [a-z] are ok;
+			 otherwise fatal.  Currently defined flags:
+				Deleted		branch is deleted
+
+
+<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)
+eg
+	ijackson@chiark.greenend.org.uk/2012-01-20T225127Z/reorg/sponge
+NB only exactly that date format is allowed and timezone must be Z.
+
+Branches may be specified as
+	[<email>@[<domain.name>/][<date-spec>/]<nickname-path-spec>
+
+<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 branches are candidates; when we come
+		to select, take the branch nearest that date rather than
+		the most recent; the date spec is intepreted by date -d
+		after ~s have been replaced by spaces
+	A prefix of the ISO8601 date spec, stopping just after a
+		numeric component (or at the end)
+
+So overall, if the current branch is
+	ijackson@chiark.greenend.org.uk/2011-08-20T120320Z/fixes/pudding
+then all of the following can refer to the same branch
+	./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
+
+Search algorithm:
+	1. prefer branches with email address (or domain)
+	   matching current branch
+	2. prefer branches with our own email address (or domain)
+	3. other branches
+Within this there may be branches with multiple dates; prefer the most
+recent.
-- 
2.30.2