234842a347
Install new git hooks in this version. This does beg the question of what to do if git later gets eg a post-smudge hook, that could run git-annex smudge --update. I think the thing to do in that case would be to make git-annex smudge --update install the new hooks. That way, as the user uses git-annex, the hook would be created pretty quickly and without needing any extra syscalls except for when git-annex smudge --update is called. I considered doing something like that for installation of the post-checkout and post-merge hooks, which would have avoided the need for v7. But the only place it was cheap to do it would be in git-annex smudge which could cheaply notice that smudge.log didn't exist yet and so know the hooks needed to be installed. But since smudge used to populate pointer files, it would be quite surprising if a single git checkout/merge failed to update the work tree, and so that idea didn't work out. The other reason for v7 is psychological -- users don't need to worry about whether they might be running an old version of git-annex that doesn't support their v7 repository very well. And bug reports about "v6" have gotten a bit of a bad association in my head since they often hit one of the known limitations and didn't realize it was experimental. newtyped RepoVersion Int to avoid needing 2 comparisons in versionSupportsUnlockedPointers etc. Also it's just nicer. This commit was sponsored by John Pellman on Patreon.
176 lines
6.3 KiB
Markdown
176 lines
6.3 KiB
Markdown
[[!toc levels=3]]
|
|
|
|
# Software upgrades
|
|
|
|
Upgrading the code base of git-annex will be done differently depending on
|
|
your [[install]] method. For most distribution-based packages, it is
|
|
handled by the package management software.
|
|
|
|
For the standalone distribution, the [[git-annex-webapp]](1) will ask the
|
|
user for confirmation when it detects a new version. Once that is
|
|
confirmed, or if `annex.autoupgrade` is enabled (see the [[git-annex]](1)
|
|
manpage) the assistant will start the upgrade. The upgrade process is
|
|
fairly simple: the assistant will move the `git-annex.linux` directory out
|
|
of the way and replace it with the new version, then re-execute itself. It
|
|
therefore needs write access to the parent directory of the
|
|
`git-annex.linux` directory.
|
|
|
|
Note that "upgrading" from a distribution-based package to the
|
|
[[install/Linux_standalone/]] version may cause weird problems, as an
|
|
unexpected version of git-annex (e.g. the old one from packages) may be
|
|
ran.
|
|
|
|
# Repository upgrades
|
|
|
|
Occasionally improvements 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 commitment 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.
|
|
|
|
The upgrade process needs to write to the repository. If the original
|
|
repository cannot be written to (due to eg being on readonly media),
|
|
the upgrade would need to be run in a copy of the repository.
|
|
|
|
The upgrade events, so far:
|
|
|
|
## v6 -> v7 (git-annex version 7.x)
|
|
|
|
The upgrade from v5 to v7 is handled manually for now.
|
|
Run `git-annex upgrade` to perform the upgrade.
|
|
|
|
v6 repositories are automatically upgraded to v7.
|
|
|
|
The only difference between v6 and v7 is that some additional git hooks
|
|
were added in v7.
|
|
|
|
## v5 -> v6 (git-annex version 6.x)
|
|
|
|
A v6 git-annex repository can have some files locked while other files are
|
|
unlocked, and all git and git-annex commands can be used on both locked and
|
|
unlocked files. (Although for locked files to be accessible, the filesystem
|
|
must support symbolic links..
|
|
|
|
Direct mode repositories are upgraded to instead use the new
|
|
[[adjusted branches feature|git-annex-adjust]], which transparently unlocks
|
|
all locked files in the local repository.
|
|
|
|
The behavior of some commands changes in an upgraded repository:
|
|
|
|
* `git add` will add files to the annex, rather than adding them directly
|
|
to the git repository. To cause some files to be added directly
|
|
to git, you can configure `annex.largefiles`. For example:
|
|
|
|
`git config annex.largefiles "largerthan=100kb and not (include=*.c or include=*.h)"`
|
|
|
|
* `git annex unlock` and `git annex lock` change how the pointer to
|
|
the annexed content is stored in git.
|
|
|
|
There is also a new `annex.thin` setting, which makes unlocked files in v6
|
|
repositories be hard linked to their content, instead of a copy. This saves
|
|
disk space but means any modification of an unlocked file will lose the
|
|
local (and possibly only) copy of the old version. This is automatically
|
|
enabled when upgrading a direct mode repository, since direct mode made the
|
|
same tradeoff.
|
|
|
|
See [[tips/unlocked_files/]] for more details about locked files and thin
|
|
mode.
|
|
|
|
## v4 -> v5 (git-annex version 5.x)
|
|
|
|
The upgrade from v4 to v5 is handled
|
|
automatically, and only affects [[direct mode]] repositories.
|
|
|
|
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
|