Add documentation for copy command

doc/045_working_with_repos.rst

@@ -82,6 +82,66 @@ Furthermore you can group the output by the same filters (host, paths, tags):
     1 snapshots
 
 
+Copying snapshots between repositories
+======================================
+
+In case you want to transfer snapshots between two repositories, for
+example from a local to a remote repository, you can use the ``copy`` command:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo copy --repo2 /srv/restic-repo-copy
+    repository d6504c63 opened successfully, password is correct
+    repository 3dd0878c opened successfully, password is correct
+
+    snapshot 410b18a2 of [/home/user/work] at 2020-06-09 23:15:57.305305 +0200 CEST)
+      copy started, this may take a while...
+    snapshot 7a746a07 saved
+
+    snapshot 4e5d5487 of [/home/user/work] at 2020-05-01 22:44:07.012113 +0200 CEST)
+    skipping snapshot 4e5d5487, was already copied to snapshot 50eb62b7
+
+The example command copies all snapshots from the source repository
+``/srv/restic-repo`` to the destination repository ``/srv/restic-repo-copy``.
+Snapshots which have previously been copied between repositories will
+be skipped by later copy runs.
+
+.. note:: Note that this process will have to read (download) and write (upload) the
+    entire snapshot(s) due to the different encryption keys used in the source and
+    destination repository. Also, the transferred files are not re-chunked, which
+    may break deduplication between files already stored in the destination repo
+    and files copied there using this command.
+
+For the destination repository ``--repo2`` the password can be read from
+a file ``--password-file2`` or from a command ``--password-command2``.
+Alternatively the environment variables ``$RESTIC_PASSWORD_COMMAND2`` and
+``$RESTIC_PASSWORD_FILE2`` can be used. It is also possible to directly
+pass the password via ``$RESTIC_PASSWORD2``. The key which should be used
+for decryption can be selected by passing its ID via the flag ``--key-hint2``
+or the environment variable ``$RESTIC_KEY_HINT2``.
+
+In case the source and destination repository use the same backend, then
+configuration options and environment variables to configure the backend
+apply to both repositories. For example it might not be possible to specify
+different accounts for the source and destination repository. You can
+avoid this limitation by using the rclone backend along with remotes which
+are configured in rclone.
+
+The list of snapshots to copy can be filtered by host, path in the backup
+and / or a comma-separated tag list:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo copy --repo2 /srv/restic-repo-copy --host luigi --path /srv --tag foo,bar
+
+It is also possible to explicitly specify the list of snapshots to copy, in
+which case only these instead of all snapshots will be copied:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo copy --repo2 /srv/restic-repo-copy 410b18a2 4e5d5487 latest
+
+
 Checking integrity and consistency
 ==================================
 

doc/manual_rest.rst

@@ -20,6 +20,7 @@ Usage help is available:
       cache         Operate on local cache directories
       cat           Print internal objects to stdout
       check         Check the repository for errors
+      copy          Copy snapshots from one repository to another
       diff          Show differences between two snapshots
       dump          Print a backed-up file to stdout
       find          Find a file, a directory or restic IDs