add v6; keep v5 working for now and manual upgrade

Since all places where a repo is used in direct mode need to have git-annex
upgraded before the repo can safely be converted to v6, the upgrade needs
to be manual for now.

I suppose that at some point I'll want to drop all the direct mode support
code. At that point, will stop supporting v5, and will need to auto-upgrade
any remaining v5 repos. If possible, I'd like to carry the direct mode
support for say, a year or so, to give people plenty of time to upgrade and
avoid disruption.

3 files changed, 34 insertions, 4 deletions

diff --git a/doc/git-annex-smudge.mdwn b/doc/git-annex-smudge.mdwn
index a4f458ee5..5186d2a17 100644
--- a/doc/git-annex-smudge.mdwn
+++ b/doc/git-annex-smudge.mdwn
@@ -17,8 +17,8 @@ but this is normally set up for you by git-annex init, so you should
 not need to configure it manually:
 
 	[filter "annex"]
-	        clean = git-annex smudge --clean %f
 	        smudge = git-annex smudge %f
+	        clean = git-annex smudge --clean %f
 
 To make git use this filter on all files except for dotfiles, put something
 like the following in the .gitattributes file:
diff --git a/doc/todo/smudge.mdwn b/doc/todo/smudge.mdwn
index 094b5f880..6e6af6f65 100644
--- a/doc/todo/smudge.mdwn
+++ b/doc/todo/smudge.mdwn
@@ -308,15 +308,17 @@ annex.version changes to 6
 
 Upgrade should be handled automatically.
 
-On upgrade, update .gitattributes with a stock configuration, unless
-it already mentions "filter=annex".
+On upgrade, update $GIT_DIR/info/attributes with a stock configuration,
+unless it already mentions "filter=annex".
 
 Upgrading a direct mode repo needs to switch it out of bare mode, and
 needs to run `git annex unlock` on all files (or reach the same result).
 So will need to stage changes to all annexed files.
 
 When a repo has some clones indirect and some direct, the upgraded repo
-will have all files unlocked, necessarily in all clones.
+will have all files unlocked, necessarily in all clones. This happens
+automatically, because when the direct repos are upgraded that causes the
+files to be unlocked, while the indirect upgrades don't touch the files.
 
 ----
 
diff --git a/doc/upgrades.mdwn b/doc/upgrades.mdwn
index f5e9cbc3a..7600d8e14 100644
--- a/doc/upgrades.mdwn
+++ b/doc/upgrades.mdwn
@@ -43,6 +43,34 @@ conflicts first before upgrading git-annex.
 
 The upgrade events, so far:
 
+## v5 -> v6 (git-annex version 6.x)
+
+The upgrade from v5 to v6 is handled manually. Run `git-annex upgrade`
+perform the upgrade.
+
+All places that a direct mode repository is cloned to should be 
+running git-annex version 6.x before you upgrade the repository.
+This is necessary because the contents of the repository are changed
+in the upgrade, and the old version of git-annex won't be able to
+access files after the repo is upgraded.
+
+If a repository is only used in indirect mode, this upgrade will not
+affect it significantly. You can use git-annex v5 and v6 in different
+clones of the same indirect mode repository without problems.
+
+This upgrade does away with the direct mode/indirect mode distinction.
+A v6 git-annex repository can have some files locked and other files
+unlocked, and all git and git-annex commands can be used on both locked and
+unlocked files. (Although for locked files to work, the filesystem
+must support symbolic links..)
+
+On upgrade, all files in a direct mode repository will be converted to
+unlocked files. The upgrade will need to stage changes to all files in
+the git repository.
+
+If a repository has some clones using direct mode and some using indirect
+mode, all the files will end up unlocked in all clones after the upgrade.
+
 ## v4 -> v5 (git-annex version 5.x)
 
 The upgrade from v4 to v5 is handled