mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
git-annex/doc/upgrades.mdwn

159 lines
6.5 KiB
Text
Raw Normal View History

fix headings
2015-06-03 14:27:23 +00:00
[[!toc levels=3]]
document the software upgrade process minimally
2015-06-03 14:24:28 +00:00
# Software upgrades
word wrap
2015-10-14 17:44:20 +00:00
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.
document the software upgrade process minimally
2015-06-03 14:24:28 +00:00
word wrap
2015-10-14 17:44:20 +00:00
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.
document the software upgrade process minimally
2015-06-03 14:24:28 +00:00
word wrap
2015-10-14 17:44:20 +00:00
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
remove broken link
2018-06-15 21:53:37 +00:00
ran.
document the software upgrade process minimally
2015-06-03 14:24:28 +00:00
# Repository upgrades
Various typo fixes in doc/*.mdwn One of my for f in `ls *.mdwn | sort -R`; do aspell -c $f; sleep 2; done sessions. 3647f704-e510-11e4-bf50-000df06acc56
2015-04-17 14:42:16 +00:00
Occasionally improvements are made to how git-annex stores its data,
upgrade documentation
2011-03-16 19:51:42 +00:00
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.
Various typo fixes in doc/*.mdwn One of my for f in `ls *.mdwn | sort -R`; do aspell -c $f; sleep 2; done sessions. 3647f704-e510-11e4-bf50-000df06acc56
2015-04-17 14:42:16 +00:00
There's a commitment that git-annex will always support upgrades from all
upgrade documentation
2011-03-16 19:51:42 +00:00
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.
No longer auto-upgrade to repository format 2, to avoid accidental upgrades, etc. Use git-annex upgrade when you're ready to run this version.
2011-03-19 22:33:39 +00:00
git-annex will notice if it is run in a repository that
typo
2019-09-13 16:58:58 +00:00
needs an upgrade, and either automatically upgrade it or
mention annex.autoupgraderepository
2019-09-13 16:26:26 +00:00
refuse to do anything. To upgrade, use the "git annex upgrade" command.
To prevent automatic upgrades in a repository, run:
fix omission
2019-09-13 16:57:31 +00:00
`git config annex.autoupgraderepository false`
upgrade documentation
2011-03-16 19:51:42 +00:00
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.
Support using v3 repositories without upgrading them to v5. An easy change now that supportedVersions is a list. Since v3 and v5 are identical other than version number, just add v3 to the list. This commit was sponsored by andrea rota.
2016-10-05 20:29:32 +00:00
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.
remove superfluous header
2015-06-03 14:28:58 +00:00
The upgrade events, so far:
upgrade documentation
2011-03-16 19:51:42 +00:00
document v8
2019-11-06 21:13:01 +00:00
## 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
tighten up docs of dotfiles changes
2020-02-19 18:29:50 +00:00
re-populated. As a consequence:
document v8
2019-11-06 21:13:01 +00:00
tighten up docs of dotfiles changes
2020-02-19 18:29:50 +00:00
* 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.
document v8
2019-11-06 21:13:01 +00:00
tighten up docs of dotfiles changes
2020-02-19 18:29:50 +00:00
* 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.
v7 to v8 auto-upgrade bump version to 8 and update NEWS about it
2019-11-07 17:23:32 +00:00
annex.dotfiles The git add behavior changes could be avoided if it turns out to be really annoying, but then it would need to behave the old way when annex.dotfiles=false and the new way when annex.dotfiles=true. I'd rather not have the config option result in such divergent behavior as `git annex add .` skipping a dotfile (old) vs adding to annex (new). Note that the assistant always adds dotfiles to the annex. This is surprising, but not new behavior. Might be worth making it also honor annex.dotfiles, but I wonder if perhaps some user somewhere uses it and keeps large files in a directory that happens to begin with a dot. Since dotfiles and dotdirs are a unix culture thing, and the assistant users may not be part of that culture, it seems best to keep its current behavior for now.
2019-12-26 20:24:40 +00:00
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.
document v8
2019-11-06 21:13:01 +00:00
v7 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.
2018-10-25 21:23:53 +00:00
## v6 -> v7 (git-annex version 7.x)
add v6; keep v5 working for now and manual upgrade Since all places where a repo is used in direct mode need to have git-annex upgraded before the repo can safely be converted to v6, the upgrade needs to be manual for now. I suppose that at some point I'll want to drop all the direct mode support code. At that point, will stop supporting v5, and will need to auto-upgrade any remaining v5 repos. If possible, I'd like to carry the direct mode support for say, a year or so, to give people plenty of time to upgrade and avoid disruption.
2015-12-04 20:14:48 +00:00
v7 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.
2018-10-25 21:23:53 +00:00
v6 repositories are automatically upgraded to v7.
The only difference between v6 and v7 is that some additional git hooks
clarify anarcat's change v7 does not need to be done simulantaneously unless you choose to use the new unlocked files feature
2018-12-05 16:22:36 +00:00
were added in v7. See below for details about what's new in v6/v7.
v7 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.
2018-10-25 21:23:53 +00:00
## v5 -> v6 (git-annex version 6.x)
v7 for all repositories * Default to v7 for new repositories. * Automatically upgrade v5 repositories to v7.
2019-08-30 17:54:57 +00:00
v5 repositories are automatically upgraded to v6.
Upgrading a direct mode repository to v6 has changed to enter an adjusted unlocked branch. This makes the direct mode to v6 upgrade able to be performed in one clone of a repository without affecting other clones, which can continue using v5 and direct mode.
2016-04-04 17:17:24 +00:00
A v6 git-annex repository can have some files locked while other files are
init: Configure .git/info/attributes to use git-annex as a smudge filter. Note that this changes the default behavior of git add in a newly initialized repository; it will add files to the annex. Don't like that this could break workflows, but it's necessary in order for any pointer files in the repo to be handled by git-annex.
2015-12-04 21:57:15 +00:00
unlocked, and all git and git-annex commands can be used on both locked and
clarify anarcat's change v7 does not need to be done simulantaneously unless you choose to use the new unlocked files feature
2018-12-05 16:22:36 +00:00
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.
Upgrading a direct mode repository to v6 has changed to enter an adjusted unlocked branch. This makes the direct mode to v6 upgrade able to be performed in one clone of a repository without affecting other clones, which can continue using v5 and direct mode.
2016-04-04 17:17:24 +00:00
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.
init: Configure .git/info/attributes to use git-annex as a smudge filter. Note that this changes the default behavior of git add in a newly initialized repository; it will add files to the annex. Don't like that this could break workflows, but it's necessary in order for any pointer files in the repo to be handled by git-annex.
2015-12-04 21:57:15 +00:00
The behavior of some commands changes in an upgraded repository:
fix formatting
2020-02-19 18:56:02 +00:00
* When `annex.largefiles` is configured, git add` will add matching
documentation for making git add only annex when configured by annex.largefiles Code change should be trvial, but not yet implemented. This significantly complicated the task of documenting how git-annex works. I'm not sure how useful the annex.gitaddtoannex confguration is after this change; seems that if a user has an annex.largefiles they will want it applied consistently. But the last thing I want to hear is more complaining from users about git add doing something they don't want it to. There's a pretty high risk users who got used to the git add behavior and don't have annex.largefiles configured will miss the NEWS and complain bitterly about their suddenly bloated repositories. Oh well. Removed outdated comments about the old behavior to avoid confusion. I don't know if I've found all the places that griping spread to.
2019-10-24 17:50:44 +00:00
files to the annex, rather than adding them directly to the git
repository.
init: Configure .git/info/attributes to use git-annex as a smudge filter. Note that this changes the default behavior of git add in a newly initialized repository; it will add files to the annex. Don't like that this could break workflows, but it's necessary in order for any pointer files in the repo to be handled by git-annex.
2015-12-04 21:57:15 +00:00
* `git annex unlock` and `git annex lock` change how the pointer to
clarify anarcat's change v7 does not need to be done simulantaneously unless you choose to use the new unlocked files feature
2018-12-05 16:22:36 +00:00
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.
mention synchronized upgrades limitation
2018-12-04 21:07:11 +00:00
Upgrading a direct mode repository to v6 has changed to enter an adjusted unlocked branch. This makes the direct mode to v6 upgrade able to be performed in one clone of a repository without affecting other clones, which can continue using v5 and direct mode.
2016-04-04 17:17:24 +00:00
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.
add v6; keep v5 working for now and manual upgrade Since all places where a repo is used in direct mode need to have git-annex upgraded before the repo can safely be converted to v6, the upgrade needs to be manual for now. I suppose that at some point I'll want to drop all the direct mode support code. At that point, will stop supporting v5, and will need to auto-upgrade any remaining v5 repos. If possible, I'd like to carry the direct mode support for say, a year or so, to give people plenty of time to upgrade and avoid disruption.
2015-12-04 20:14:48 +00:00
Upgrading a direct mode repository to v6 has changed to enter an adjusted unlocked branch. This makes the direct mode to v6 upgrade able to be performed in one clone of a repository without affecting other clones, which can continue using v5 and direct mode.
2016-04-04 17:17:24 +00:00
See [[tips/unlocked_files/]] for more details about locked files and thin
mode.
add references to annex.thin in the upgrade docs
2016-01-14 21:21:36 +00:00
remove superfluous header
2015-06-03 14:28:58 +00:00
## v4 -> v5 (git-annex version 5.x)
v5 for direct mode, with automatic upgrade This includes storing the current state of the HEAD ref, which git annex sync is going to need, but does not make sync use it.
2013-11-05 20:42:59 +00:00
update
2013-12-29 19:01:46 +00:00
The upgrade from v4 to v5 is handled
automatically, and only affects [[direct mode]] repositories.
v5 for direct mode, with automatic upgrade This includes storing the current state of the HEAD ref, which git annex sync is going to need, but does not make sync use it.
2013-11-05 20:42:59 +00:00
This upgrade involves changing direct mode repositories to operate with
core.bare=true.
remove superfluous header
2015-06-03 14:28:58 +00:00
## v3 -> v4 (git-annex version 4.x)
annex.version is now set to 4 for direct mode repositories To avoid old versions of git-annex getting confused. There is no upgrade required though. We switch back to 3 when going from direct to indirect.
2013-02-26 19:13:10 +00:00
v5 for direct mode, with automatic upgrade This includes storing the current state of the HEAD ref, which git annex sync is going to need, but does not make sync use it.
2013-11-05 20:42:59 +00:00
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.
annex.version is now set to 4 for direct mode repositories To avoid old versions of git-annex getting confused. There is no upgrade required though. We switch back to 3 when going from direct to indirect.
2013-02-26 19:13:10 +00:00
remove superfluous header
2015-06-03 14:28:58 +00:00
## v2 -> v3 (git-annex version 3.x)
upgrade documentation
2011-03-16 19:51:42 +00:00
v3 upgrade code works but write the index file a lot, so slow
2011-06-23 06:30:20 +00:00
Involved moving the .git-annex/ directory into a separate git-annex branch.
upgrade documentation
2011-03-16 19:51:42 +00:00
add
2011-06-30 20:16:52 +00:00
After this upgrade, you should make sure you include the git-annex branch
when git pushing and pulling.
remove superfluous header
2015-06-03 14:28:58 +00:00
## v1 -> v2 (git-annex version 0.20110316)
upgrade documentation
2011-03-16 19:51:42 +00:00
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.
update
2011-03-22 22:50:36 +00:00
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,
migrate: Support migrating v1 SHA keys to v2 SHA keys with size information that can be used for free space checking.
2011-03-23 21:57:10 +00:00
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]].
update
2011-03-22 22:50:36 +00:00
remove superfluous header
2015-06-03 14:28:58 +00:00
## v0 -> v1 (git-annex version 0.04)
upgrade documentation
2011-03-16 19:51:42 +00:00
Fix typos
2011-03-17 11:20:55 +00:00
Involved a reorganisation of the layout of .git/annex/. Symlinks changed.
upgrade documentation
2011-03-16 19:51:42 +00:00
Handled more or less transparently, although git-annex was just 2 weeks
old at the time, and had few users other than Joey.
Reference in a new issue Copy permalink