Document the copy command as replacement for migrate and mirror

Author: joeyates

.github/README.md

@@ -27,8 +27,7 @@ There are two types of backups:
 
 # What You Can Do with a Backup
 
-* Migrate - use the local copy to populate emails on another account. This is a once-only action that deletes any existing emails on the destination account.
-* Mirror - make a destination account match the local copy. This action can be repeated.
+* Copy - copy messages from one account to another, tracking copies in order to avoid duplicates.
 * Restore - push the local copy back to the original account.
 
 See below for a [full list of commands](#commands).
@@ -145,13 +144,12 @@ and exported via [`utils export-to-thunderbird`](/docs/commands/utils-export-to-
 # Commands
 
 * [`backup`](/docs/commands/backup.md)
+* [`copy`](/docs/commands/copy.md)
 * [`local accounts`](/docs/commands/local-accounts.md)
 * [`local check`](/docs/commands/local-check.md)
 * [`local folders`](/docs/commands/local-folders.md)
 * [`local list`](/docs/commands/local-list.md)
 * [`local show`](/docs/commands/local-show.md)
-* [`migrate`](/docs/commands/migrate.md)
-* [`mirror`](/docs/commands/mirror.md)
 * [`remote folders`](/docs/commands/remote-folders.md)
 * [`restore`](/docs/commands/restore.md)
 * [`setup`](/docs/commands/setup.md)

docs/commands/copy.md

@@ -0,0 +1,37 @@
+<!--
+# @title command: 'copy'
+-->
+# Copy
+
+```sh
+imap-backup copy SOURCE_EMAIL DESTINATION_EMAIL
+```
+
+This command makes a local copy of the emails in the source account
+and then copies them to the destination account.
+
+Exactly which folders are backed up (and copied) depends on how the account is set up.
+
+Specifically, the `folder inclusion mode (whitelist/blacklist)` and
+`folders to include/exclude` list.
+
+Note that, any messages on the destination account that is not on the source account
+are left unchanged.
+
+# Options
+
+* `--source-delimiter` - the separator between the elements of folders names
+  on the source server, defaults to `/`,
+* `--source-prefix` - optionally, a prefix element to remove from the name
+  of source folders,
+* `--destination-delimiter` - the separator between the elements of folder
+  names on the destination server, defaults to `/`,
+* `--destination-prefix` - optionally, a prefix element to add before names
+  on the destination server,
+* `--automatic-namespaces` - works out the 4 parameters above by querying
+  the source and destination IMAP servers.
+
+# Delimiters and Prefixes
+
+For details of the delimiter and prefix options,
+see [the note about delimiters and prefixes](../delimiters-and-prefixes.md).

docs/commands/migrate.md

@@ -7,6 +7,8 @@
 imap-backup migrate SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]
 ```
 
+This command is deprecated. Use [copy](./copy.md).
+
 This command copies backed up emails for one account (the "source")
 to another account (the "destination").
 

docs/commands/mirror.md

@@ -7,6 +7,8 @@
 imap-backup mirror SOURCE_EMAIL DESTINATION_EMAIL
 ```
 
+This command is deprecated and will be removed in a future version. Use [copy](./copy.md).
+
 This command makes a local copy of the emails in the source account
 and then copies them to the destination account.
 

lib/imap/backup/cli.rb

@@ -162,9 +162,12 @@ def copy(source_email, destination_email)
 
     desc(
       "migrate SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
-      "Uploads backed-up emails from account SOURCE_EMAIL to account DESTINATION_EMAIL"
+      "(Deprecated) Uploads backed-up emails from account SOURCE_EMAIL to account DESTINATION_EMAIL"
     )
     long_desc <<~DESC
+      This command is deprecated and will be removed in a future version.
+      Use 'copy' instead.
+
       All emails which have been backed up for the "source account" (SOURCE_EMAIL) are
       uploaded to the "destination account" (DESTINATION_EMAIL).
 
@@ -221,9 +224,12 @@ def migrate(source_email, destination_email)
 
     desc(
       "mirror SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
-      "Keeps the DESTINATION_EMAIL account aligned with the SOURCE_EMAIL account"
+      "(Deprecated) Keeps the DESTINATION_EMAIL account aligned with the SOURCE_EMAIL account"
     )
     long_desc <<~DESC
+      This command is deprecated and will be removed in a future version.
+      Use 'copy' instead.
+
       This command updates the DESTINATION_EMAIL account's folders to have the same contents
       as those on the SOURCE_EMAIL account.