Merge pull request #3704 from MichaelEischer/compression-migrations

Support migration to repository format with compression

doc/030_preparing_a_new_repo.rst

@@ -40,7 +40,17 @@ options exist:
    be used to explicitely set the version for the new repository. By default,
    the current stable version is used. Have a look at the `design documentation
    <https://github.com/restic/restic/blob/master/doc/design.rst>`__ for
-   details.
+   details. The alias ``latest`` will always point to the latest repository version.
+   The below table shows which restic version is required to use a certain
+   repository version and shows new features introduced by the repository format.
+
++--------------------+------------------------+---------------------+
+| Repository version | Minimum restic version | Major new features  |
++====================+========================+=====================+
+| ``1``              | any version            |                     |
++--------------------+------------------------+---------------------+
+| ``2``              | >= 0.14.0              | Compression support |
++--------------------+------------------------+---------------------+
 
 
 Local

doc/045_working_with_repos.rst

@@ -298,3 +298,26 @@ a file size value the following command may be used:
 
     $ restic -r /srv/restic-repo check --read-data-subset=50M
     $ restic -r /srv/restic-repo check --read-data-subset=10G
+
+
+Upgrading the repository format version
+=======================================
+
+Repositories created using earlier restic versions use an older repository
+format version and have to be upgraded to allow using all new features.
+Upgrading must be done explicitly as a newer repository version increases the
+minimum restic version required to access the repository. For example the
+repository format version 2 is only readable using restic 0.14.0 or newer.
+
+Upgrading to repo version 2 is a two step process: first run
+``migrate upgrade_repo_v2`` which will check the repository integrity and
+then upgrade the repository version. Repository problems must be corrected
+before the migration will be possible. After the migration is complete, run
+``prune`` to compress the repository metadata. To limit the amount of data
+rewritten in at once, you can use the ``prune --max-repack-size size``
+parameter, see :ref:`customize-pruning` for more details.
+
+File contents stored in the repository will not be rewritten, data from new
+backups will be compressed. Over time more and more of the repository will
+be compressed. To speed up this process and compress all not yet compressed
+data, you can run ``prune --repack-uncompressed``.

doc/060_forget.rst

@@ -388,6 +388,8 @@ the specified duration: if ``forget --keep-within 7d`` is run 8 days after the
 last good snapshot, then the attacker can still use that opportunity to remove
 all legitimate snapshots.
 
+.. _customize-pruning:
+
 Customize pruning
 *****************