176 lines
7.2 KiB
Markdown
176 lines
7.2 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 either automatically upgrade it or
|
|
refuse to do anything. To upgrade, use the "git annex upgrade" command.
|
|
|
|
To prevent automatic upgrades in a repository, run:
|
|
`git config annex.autoupgraderepository false`
|
|
|
|
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:
|
|
|
|
## v9 -> v10 (git-annex version 10.x)
|
|
|
|
v10 repositories change a fundamental part of how git-annex does locking.
|
|
|
|
v9 repositories are automatically upgraded to v10, but with a delay.
|
|
The upgrade happens one year after the repository was upgraded to v9.
|
|
This delay is because it would not be safe to upgrade to v10 if a
|
|
git-annex process version 8.x was still running. Waiting a year makes
|
|
it very unlikely that such a process is still running.
|
|
|
|
## v8 -> v9 (git-annex version 10.x)
|
|
|
|
v8 repositories are not yet automatically upgraded to v9.
|
|
|
|
v9 is a stepping stone to the v10 upgrade. By adding this intermediate
|
|
version, old versions of git-annex that only support v8 will not be able to
|
|
start new processes in the repository after the v9 upgrade.
|
|
|
|
## v7 -> v8 (git-annex version 8.x)
|
|
|
|
v7 repositories are automatically upgraded to v8.
|
|
|
|
Some sqlite databases that git-annex uses were changed in v8 and have to be
|
|
re-populated. As a consequence:
|
|
|
|
* Any incremental fscks that were started in v7 won't resume where they left
|
|
off in v8, but will instead begin again from the first file.
|
|
|
|
* An interrupted export that was started in v7 won't resume where it left off
|
|
after upgrade to v8; files will be re-uploaded to the export remote.
|
|
|
|
* After the upgrade, git-annex will in some situations have to do extra
|
|
work while it finishes populating the new databases. After this one-time
|
|
speed cost, git-annex's speed will improve when using the new and improved
|
|
databases.
|
|
|
|
Also, there are some behavior changes around adding dotfiles. While before
|
|
git-annex add skipped adding dotfiles when operating on whole directories,
|
|
and added dotfiles that were explicitly listed to the annex, it now adds
|
|
dotfiles to git by default, unless annex.dotfiles is set to true.
|
|
|
|
## v6 -> v7 (git-annex version 7.x)
|
|
|
|
v6 repositories are automatically upgraded to v7.
|
|
|
|
The only difference between v6 and v7 is that some additional git hooks
|
|
were added in v7. See below for details about what's new in v6/v7.
|
|
|
|
## v5 -> v6 (git-annex version 6.x)
|
|
|
|
v5 repositories are automatically upgraded to v6.
|
|
|
|
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. It's a good idea to make sure that all users of the
|
|
repository have upgraded git-annex and upgraded their repositories
|
|
to the new version before starting to use this feature, since old
|
|
versions of git-annex will ignore the new unlocked files.
|
|
|
|
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:
|
|
|
|
* When `annex.largefiles` is configured, git add` will add matching
|
|
files to the annex, rather than adding them directly to the git
|
|
repository.
|
|
|
|
* `git annex unlock` and `git annex lock` change how the pointer to
|
|
the annexed content is stored in git. If you commit the change,
|
|
that will impact all clones of the repository. This means all clones of the
|
|
repository will need to run at least v6 to correctly synchronise.
|
|
|
|
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.
|
|
|
|
## 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]].
|
|
|
|
## 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.
|