v3 upgrade code works

but write the index file a lot, so slow

1 files changed, 43 insertions, 28 deletions

diff --git a/doc/upgrades.mdwn b/doc/upgrades.mdwn
index 516e5b3bb..bf12f7e43 100644
--- a/doc/upgrades.mdwn
+++ b/doc/upgrades.mdwn
@@ -7,49 +7,38 @@ There's a committment that git-annex will always support upgrades from all
 past versions. After all, you may have offline drives from an earlier
 git-annex, and might want to use them with a newer git-annex.
 
-## Upgrade process
-
 git-annex will notice if it is run in a repository that
 needs an upgrade, and refuse to do anything. To upgrade,
 use the "git annex upgrade" command. The upgrade can tend
 to take a while, if you have a lot of files.
 
-Each clone of a repository should be individually upgraded.
-Until a repository's remotes have been upgraded, git-annex
-will refuse to communicate with them.
-
-Generally, start by upgrading one repository, and then you can commit
-the changes git-annex staged during upgrade, and push them out to other
-repositories. And then upgrade those other repositories. Doing it this
-way avoids git-annex doing some duplicate work during the upgrade.
-
 The upgrade process is guaranteed to be conflict-free. Unless you
 already have git conflicts in your repository or between repositories.
 Upgrading a repository with conflicts is not recommended; resolve the
 conflicts first before upgrading git-annex.
 
-Example upgrade process:
+## Upgrade events, so far
 
-	cd localrepo
-	git pull
-	git annex upgrade
-	(Upgrading object directory layout v1 to v2...)
-	git commit -m "upgrade v1 to v2"
-	git push
+### v2 -> v3 (git-annex version 3.x)
 
-	ssh remote
-	cd remoterepo
-	git pull
-	git annex upgrade
-	...
+Involved moving the .git-annex/ directory into a separate git-annex branch.
 
-## Upgrade events, so far
+### tips for this upgrade
 
-### v2 -> v3 (git-annex version 0.20110610 to version 0.20110622)
+This upgrade is easier than the previous upgrades. You don't need to
+upgrade every repository at once; it's sufficient to upgrade each
+repository only when you next use it.
 
-Involved moving the .git-annex/ directory into a separate git-annex branch.
+This upgrade can be sped up by, before you start, making
+.git/index.git-annex into a symlink to a file on a ramdisk.
+For example: `ln -s /run/shm/index.git-annex.$(git config annex.uuid) .git/index.git-annex`
+but, if you do that, be sure to remove the symlink after the upgrade!
 
-### v1 -> v2 (git-annex version 0.23 to version 0.20110316)
+After the upgrade is complete, commit the changes it staged.
+	
+	git commit -m "upgrade v2 to v3"
+
+### v1 -> v2 (git-annex version 0.20110316)
 
 Involved adding hashing to .git/annex/ and changing the names of all keys.
 Symlinks changed.
@@ -64,7 +53,33 @@ and that information will be used by git-annex for disk free space checking.
 To ensure that information is available for all your annexed files, see
 [[upgrades/SHA_size]].
 
-### v0 -> v1 (git-annex version 0.03 to version 0.04)
+### tips for this upgrade
+
+Each clone of a repository should be individually upgraded.
+Until a repository's remotes have been upgraded, git-annex
+will refuse to communicate with them.
+
+Start by upgrading one repository, and then you can commit
+the changes git-annex staged during upgrade, and push them out to other
+repositories. And then upgrade those other repositories. Doing it this
+way avoids git-annex doing some duplicate work during the upgrade.
+
+Example upgrade process:
+
+	cd localrepo
+	git pull
+	git annex upgrade
+	(Upgrading object directory layout v1 to v2...)
+	git commit -m "upgrade v1 to v2"
+	git push
+
+	ssh remote
+	cd remoterepo
+	git pull
+	git annex upgrade
+	...
+
+### v0 -> v1 (git-annex version 0.04)
 
 Involved a reorganisation of the layout of .git/annex/. Symlinks changed.