upgrade documentation

1 files changed, 67 insertions, 0 deletions

diff --git a/doc/upgrades.mdwn b/doc/upgrades.mdwn
new file mode 100644
index 000000000..245212124
--- /dev/null
+++ b/doc/upgrades.mdwn
@@ -0,0 +1,67 @@
+Occasionally improvments are made to how git-annex stores its data,
+that require an upgrade process to convert repositories made with an older
+version to be used by a newer version. It's annoying, it should happen
+rarely, but sometimes, it's worth it.
+
+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 automatically notice if it is run in a repository that
+needs an upgrade, and perform the upgrade before running whatever it
+was asked to do. Or you can use the "git annex upgrade" command to
+explicitly do an upgrade. 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
+may 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:
+
+	cd localrepo
+	git pull
+	git annex upgrade
+	(Upgrading object directory layout v1 to v2...)
+	git commit -a -m "upgrade v1 to v2"
+	git push
+
+	ssh remote
+	cd remoterepo
+	git pull
+	git annex upgrade
+	...
+
+## Upgrade events, so far
+
+### v1 -> v2 (git-annex version 0.23 to version 0.20110316)
+
+Involved adding hashing to .git/annex/ and changing the names of all keys.
+Symlinks changed.
+
+Also, hashing was added to location log files in .git-annex/.
+And .gitattributes needed to have another line added to it.
+
+Handled transparently.
+
+### v0 -> v1 (git-annex version 0.03 to version 0.04)
+
+Involved a reogranisation of the layout of .git/annex/. Symlinks changed.
+
+Handled more or less transparently, although git-annex was just 2 weeks
+old at the time, and had few users other than Joey.
+
+This upgrade is belived to still be supported, but has not been tested
+lately.