856ce5cf5f
v10 will run 1 year after the upgrade to v9, to give time for any v8 processes to die. Until that point, the v10 upgrade will be tried by every process but deferred, so added support for deferring upgrades. The upgrade prevention lock file that will be used by v10 is not yet implemented, so it does not yet defer. Sponsored-by: Dartmouth College's Datalad project
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 automatically upgraded to v9.
|
|
|
|
Starting in v9, upgrades to a repository are prevented while another
|
|
git-annex command is running. That is needed for the v10 repository
|
|
upgrade to be performed safely.
|
|
|
|
## 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.
|