concrete design

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/design/v6.mdwn b/doc/design/v6.mdwn
index aaec302a8..f7309a636 100644
--- a/doc/design/v6.mdwn
+++ b/doc/design/v6.mdwn
@@ -190,3 +190,42 @@ The former would be more flexible. The latter is simpler.
 The former also lets the user chose *no* hash directories, or 
 choose 2 levels of hash directories while using the (v5 default) mixed
 case hashing.
+
+## concrete design
+
+Make git-annex:version be used by newer git-annex versions than v5,
+and by nonstandard configurations.
+
+The file contents will be "timestamp uuid [value, ..]", where value is a
+serialized data type that describes divergence from v5 (since v5 and older
+don't have the git-annex:version file).
+
+So, for example, "[Version 6]" could indicate that v6 is being used. Or,
+"[ObjectHashLower True, ObjectHashDirectories 1, BranchHashDirectories 1]"
+indicate a nonstandard configuration on top of v5 (this might turn out to
+be identical to v6; just make the compare equal and no problem).
+
+git-annex merge would check if it's merging in a git-annex:version from
+another repo that doesn't match the git-annex:version of the local repo,
+and abort. git-annex sync (and the assistant) would check the same, but
+before merging master branches either, to avoid a bad merge there.
+
+The git-annex:version of a local repo could be changed by an upgrade
+or some sort of transition. When this happens, the new value is written
+for the uuid of the local repo. git-annex merge would then refuse to merge
+with remote repos until they were also transitioned to the new version.
+
+(There's perhaps some overlap here with the existing
+git-annex:transitions.log, however the current transitions involve
+forgetting history/dead remotes and so can be done repeatedly on a
+repository. Also, the current transitions can be performed on remote
+branches before merging them in; that wouldn't work well for version
+changes since those require other changes in the remote repo.)
+
+Not covered:
+
+* git-merge of other branches, such as master (can be fixed by `git annex
+  fix` or `fsck`)
+* Old versions of git-annex will ignore the version file of course,
+  and so merging such repos using them can result in pain.
+