1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
[[!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, see [[bugs/git-annex-shell_doesn__39__t_work_as_expected/]] for a full
discussion.
# 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 events, so far:
## v5 -> v6 (git-annex version 6.x)
The upgrade from v5 to v6 is handled manually. Run `git-annex upgrade`
perform the upgrade.
Warning: All places that a direct mode repository is cloned to should be
running git-annex version 6.x before you upgrade the repository.
This is necessary because the contents of the repository are changed
in the upgrade, and the old version of git-annex won't be able to
access files after the repo is upgraded.
This upgrade does away with the direct mode/indirect mode distinction.
A v6 git-annex repository can have some files locked and other files
unlocked, and all git and git-annex commands can be used on both locked and
unlocked files. (Although for locked files to work, the filesystem
must support symbolic links..)
The behavior of some commands changes in an upgraded repository:
* `git add` will add files to the annex, in unlocked mode, 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.
On upgrade, all files in a direct mode repository will be converted to
unlocked files. The upgrade will stage changes to all annexed files in
the git repository, which you can then commit.
If a repository has some clones using direct mode and some using indirect
mode, all the files will end up unlocked in all clones after the 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
|
