From 1dd06357f0a55c2b92b3fdad328971b6147b45b0 Mon Sep 17 00:00:00 2001 From: Joe Yates Date: Mon, 1 Apr 2024 11:26:58 +0200 Subject: [PATCH] Document the copy command as replacement for migrate and mirror --- .github/README.md | 6 ++---- docs/commands/copy.md | 37 +++++++++++++++++++++++++++++++++++++ docs/commands/migrate.md | 2 ++ docs/commands/mirror.md | 2 ++ lib/imap/backup/cli.rb | 10 ++++++++-- 5 files changed, 51 insertions(+), 6 deletions(-) create mode 100644 docs/commands/copy.md diff --git a/.github/README.md b/.github/README.md index fb505f4e..b8e5476d 100644 --- a/.github/README.md +++ b/.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) diff --git a/docs/commands/copy.md b/docs/commands/copy.md new file mode 100644 index 00000000..6b1b1295 --- /dev/null +++ b/docs/commands/copy.md @@ -0,0 +1,37 @@ + +# 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). diff --git a/docs/commands/migrate.md b/docs/commands/migrate.md index e8973c36..acc11d26 100644 --- a/docs/commands/migrate.md +++ b/docs/commands/migrate.md @@ -7,6 +7,8 @@ imap-backup migrate SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS] ``` +This command is deprecated and will be removed in a future version. Use [copy](./copy.md). + This command copies backed up emails for one account (the "source") to another account (the "destination"). diff --git a/docs/commands/mirror.md b/docs/commands/mirror.md index 6fbd251d..7470c0ab 100644 --- a/docs/commands/mirror.md +++ b/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. diff --git a/lib/imap/backup/cli.rb b/lib/imap/backup/cli.rb index 119940ab..442e154d 100644 --- a/lib/imap/backup/cli.rb +++ b/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.