e658010128
v7 does not need to be done simulantaneously unless you choose to use the new unlocked files feature
183 lines
6.7 KiB
Markdown
183 lines
6.7 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. See below for details about what's new in v6/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. 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:
|
|
|
|
* `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. 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.
|
|
|
|
Run git-annex upgrade to perform this upgrade.
|
|
|
|
## 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
|