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. Previously, files added to the SHA [[backends]] did not have their file size tracked, while files added to the WORM backend did. Files added to the SHA backends after the conversion will have their file size tracked, 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) 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.