migrate: Support migrating v1 SHA keys to v2 SHA keys with size information that can be used for free space checking.

3 files changed, 30 insertions, 5 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index d7b57675d..81cea04cd 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -162,10 +162,15 @@ Many git-annex commands will stage changes for later `git commit` by you.
 * migrate [path ...]
 
   Changes the specified annexed files to store their content in the
-  default backend (or the one specified with --backend).
+  default backend (or the one specified with --backend). Only files whose
+  content is currently available are migrated.
 
   Note that the content is not removed from the backend it was previously in.
-  Use `git annex unused` to find and remove such content. 
+  Use `git annex unused` to find and remove such content.
+
+  Normally, nothing will be done to files already in the backend.
+  However, if a backend changes the information it uses to construct a key,
+  this can also be used to migrate files to use the new key format.
 
 * map
 
diff --git a/doc/upgrades.mdwn b/doc/upgrades.mdwn
index dbea5e9c4..0a07ef7aa 100644
--- a/doc/upgrades.mdwn
+++ b/doc/upgrades.mdwn
@@ -56,9 +56,9 @@ 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 space checking.
-There is not yet a way to add file size tracking information to old files
-in the SHA backend.
+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.03 to version 0.04)
 
diff --git a/doc/upgrades/SHA_size.mdwn b/doc/upgrades/SHA_size.mdwn
new file mode 100644
index 000000000..319b91108
--- /dev/null
+++ b/doc/upgrades/SHA_size.mdwn
@@ -0,0 +1,20 @@
+Before version 2 of the git-annex repository, files added to the SHA
+[[backends]] did not have their file size tracked, while files added to the
+WORM backend did. The file size information is used for disk free space
+checking.
+
+Files added to the SHA backends after the conversion will have their file
+size tracked automatically. This disk free space checking is an optional
+feature and since you're more likely to be using more recently added files,
+you're unlikely to see any bad effect if you do nothing.
+
+That said, if you have old files added to SHA backends that lack file size
+tracking info, here's how you can add that info. After [[upgrading|upgrades]]
+to repository version 2, in each repository run:
+
+	git annex migrate
+	git commit -m 'migrated keys for v2'
+
+The usual caveats about [[walkthrough/migrating_data_to_a_new_backend]]
+apply; you will end up with unused keys that you can later clean up with
+`git annex unused`.