diff options
Diffstat (limited to 'doc/upgrades.mdwn')
-rw-r--r-- | doc/upgrades.mdwn | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/doc/upgrades.mdwn b/doc/upgrades.mdwn new file mode 100644 index 000000000..5cf4093dc --- /dev/null +++ b/doc/upgrades.mdwn @@ -0,0 +1,106 @@ +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. + +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 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. + +## Upgrade events, so far + +### v4 -> v5 (git-annex version 5.x) + +v5 is only used for [[direct_mode]]. The upgrade from v4 to v5 is handled +automatically. + +This upgrade involves changing direct mode repositories to operate with +core.bare=true. + +### v3 -> v4 (git-annex version 4.x) + +v4 was only used for [[direct_mode]], to ensure that a version of git-annex +that understands direct mode was used with a direct mode repository. + +### v2 -> v3 (git-annex version 3.x) + +Involved moving the .git-annex/ directory into a separate git-annex branch. + +After this upgrade, you should make sure you include the git-annex branch +when git pushing and pulling. + +### tips for this upgrade + +This upgrade is easier (and faster!) 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. + +Example upgrade process: + + cd localrepo + git pull + git annex upgrade + git commit -m "upgrade v2 to v3" + git gc + +### v1 -> v2 (git-annex 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]]. + +### tips for this upgrade + +This 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. + +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 + 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. + +Handled more or less transparently, although git-annex was just 2 weeks +old at the time, and had few users other than Joey. + +Before doing this upgrade, set annex.version: + + git config annex.version 0 |