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 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:

	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
	...

## 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.

### v0 -> v1 (git-annex version 0.03 to version 0.04)

Involved a reorganisation 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 believed to still be supported, but has not been tested
lately.