imap-backup 15.1.3 → 16.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a391a879278c1f286d5756ebfc3e77c39acda7e5ec9441776e30fb720251cee
-  data.tar.gz: bcd9c851be504e9c775a241a21e1ecc708baf4f05ff7fe42160e7468c10ca3f3
+  metadata.gz: bf6997d289ca5babbecd35e683ede921273300779f3f7dac95e247c0478f1814
+  data.tar.gz: '009892c47699a0cc94ff28c2d3ea7346915732b7dc86c7231b7e606302219888'
 SHA512:
-  metadata.gz: 289206eb94864c60e82b35db46e9f5d7531f73692bd10c02d407e800c77aa00597a149cfc7d05f749abe8d8189745a4b9b5a184fd8df472ea13d646fe8065105
-  data.tar.gz: b38e2740e7862fc92175a684dfd93a3b176ed3b8e56ae2ee6438490577ab54002238ecdf4d6f1449d0c557ca5996eea1b81f6aabbb6aaaa47ad455796b431903
+  metadata.gz: 46bdbccf9be3efade25e500f6c67f37de4fc0a0aa8514b55f8eabf7e1171042b5be87d029f37d9cb449c23d1fcf0d5fd2a20c2e8595c6149eff0c20f89e6b3d3
+  data.tar.gz: d507a668897c325e2cc771d69b083f9929247b839b55d1fe86bfaeac3ee8be40df43b9f634d4f97c0188fe3bcbfba666456a9131236103455020fb45ecec9d61

data/imap-backup.gemspec

@@ -21,10 +21,12 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = ">= 3.0"
 
   gem.add_runtime_dependency "highline"
+  gem.add_runtime_dependency "logger"
   gem.add_runtime_dependency "mail", "2.7.1"
   gem.add_runtime_dependency "net-imap", ">= 0.3.2"
   gem.add_runtime_dependency "net-smtp"
   gem.add_runtime_dependency "os"
+  gem.add_runtime_dependency "ostruct"
   gem.add_runtime_dependency "rake"
   gem.add_runtime_dependency "thor", "~> 1.1"
   gem.add_runtime_dependency "thunderbird", "0.3.0"

data/lib/imap/backup/account/client_factory.rb

@@ -1,9 +1,7 @@
 require "socket"
 
-require "imap/backup/client/apple_mail"
 require "imap/backup/client/automatic_login_wrapper"
 require "imap/backup/client/default"
-require "imap/backup/email/provider"
 
 module Imap; end
 
@@ -14,39 +12,17 @@ module Imap::Backup
   class Account::ClientFactory
     def initialize(account:)
       @account = account
-      @provider = nil
-      @server = nil
     end
 
     # @return [Client::AutomaticLoginWrapper] a client for the account
     def run
-      options = provider_options
-      Logger.logger.debug(
-        "Creating IMAP instance: #{server}, options: #{options.inspect}"
-      )
-      client =
-        if provider.is_a?(Email::Provider::AppleMail)
-          Client::AppleMail.new(server, account, options)
-        else
-          Client::Default.new(server, account, options)
-        end
+      Logger.logger.debug("Creating IMAP instance")
+      client = Client::Default.new(account)
       Client::AutomaticLoginWrapper.new(client: client)
     end
 
     private
 
     attr_reader :account
-
-    def provider
-      @provider ||= Email::Provider.for_address(account.username)
-    end
-
-    def provider_options
-      provider.options.merge(account.connection_options || {})
-    end
-
-    def server
-      @server ||= account.server || provider.host
-    end
   end
 end

data/lib/imap/backup/account/folder.rb

@@ -38,7 +38,6 @@ module Imap::Backup
       Logger.logger.debug "Folder '#{name}' exists"
       true
     rescue FolderNotFound
-      Logger.logger.debug "Folder '#{name}' does not exist"
       false
     end
 
@@ -67,7 +66,10 @@ module Imap::Backup
     def uids
       Logger.logger.debug "Fetching UIDs for folder '#{name}'"
       examine
-      result = client.uid_search(["ALL"]).sort
+      result =
+        retry_on_error(errors: UID_SEARCH_RETRY_CLASSES) do
+          client.uid_search(["ALL"]).sort
+        end
       Logger.logger.debug "#{result.count} UIDs found for folder '#{name}'"
       result
     rescue FolderNotFound
@@ -177,6 +179,7 @@ module Imap::Backup
 
     BODY_ATTRIBUTE = "BODY[]".freeze
     UID_FETCH_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::IOError].freeze
+    UID_SEARCH_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::IOError].freeze
     APPEND_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
     CREATE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
     EXAMINE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
@@ -185,9 +188,9 @@ module Imap::Backup
     def examine
       client.examine(utf7_encoded_name)
     rescue Net::IMAP::NoResponseError
-      Imap::Backup::Logger.logger.warn "Folder '#{name}' does not exist on server"
-      Imap::Backup::Logger.logger.warn caller.join("\n")
-      raise FolderNotFound, "Folder '#{name}' does not exist on server"
+      message = "Folder '#{name}' does not exist on server"
+      Imap::Backup::Logger.logger.warn message
+      raise FolderNotFound, message
     end
 
     def extract_uid(response)

data/lib/imap/backup/account.rb

@@ -211,11 +211,7 @@ module Imap::Backup
     def multi_fetch_size
       @multi_fetch_size ||= begin
         int = @multi_fetch_size_orignal.to_i
-        if int.positive?
-          int
-        else
-          DEFAULT_MULTI_FETCH_SIZE
-        end
+        int.positive? ? int : DEFAULT_MULTI_FETCH_SIZE
       end
     end
 

data/lib/imap/backup/cli/helpers.rb

@@ -16,6 +16,28 @@ module Imap::Backup
       options.define_options
     end
 
+    # @return [String] a description of the namespace configuration
+    NAMESPACE_CONFIGURATION_DESCRIPTION = <<~DESC.freeze
+      Some IMAP servers use namespaces (i.e. prefixes like "INBOX"),
+      while others, while others concatenate the names of subfolders
+      with a charater ("delimiter") other than "/".
+
+      In these cases there are two choices.
+
+      You can use the `--automatic-namespaces` option.
+      This will query the source and detination servers for their
+      namespace configuration and will adapt paths accordingly.
+      This option requires that both the source and destination
+      servers are available and work with the provided parameters
+      and authentication.
+
+      If automatic configuration does not work as desired, there are the
+      `--source-prefix=`, `--source-delimiter=`,
+      `--destination-prefix=` and `--destination-delimiter=` parameters.
+      To check what values you should use, check the output of the
+      `imap-backup remote namespaces EMAIL` command.
+    DESC
+
     # Processes command-line parameters
     # @return [Hash] the supplied command-line parameters with
     #   with hyphens in keys replaced by underscores

data/lib/imap/backup/cli/migrate.rb

@@ -0,0 +1,79 @@
+module Imap; end
+
+module Imap::Backup
+  # Processes parameters to run the `migrate` command via command-line parameters
+  module CLI::Migrate
+    include Thor::Actions
+    include CLI::Helpers
+
+    LONG_DESCRIPTION = <<~DESC.freeze
+      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).
+
+      Some configuration may be necessary, as follows:
+
+      #{CLI::Helpers::NAMESPACE_CONFIGURATION_DESCRIPTION}
+
+      Finally, if you want to delete existing emails in destination folders,
+      use the `--reset` option. In this case, all existing emails are
+      deleted before uploading the migrated emails.
+    DESC
+
+    def self.included(base)
+      base.class_eval do
+        desc(
+          "migrate SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
+          "(Deprecated) Uploads backed-up emails from account SOURCE_EMAIL " \
+          "to account DESTINATION_EMAIL"
+        )
+        long_desc LONG_DESCRIPTION
+        config_option
+        quiet_option
+        verbose_option
+        method_option(
+          "automatic-namespaces",
+          type: :boolean,
+          desc: "automatically choose delimiters and prefixes"
+        )
+        method_option(
+          "destination-delimiter",
+          type: :string,
+          desc: "the delimiter for destination folder names"
+        )
+        method_option(
+          "destination-prefix",
+          type: :string,
+          desc: "the prefix (namespace) to add to destination folder names",
+          aliases: ["-d"]
+        )
+        method_option(
+          "reset",
+          type: :boolean,
+          desc: "DANGER! This option deletes all messages from destination " \
+                "folders before uploading",
+          aliases: ["-r"]
+        )
+        method_option(
+          "source-delimiter",
+          type: :string,
+          desc: "the delimiter for source folder names"
+        )
+        method_option(
+          "source-prefix",
+          type: :string,
+          desc: "the prefix (namespace) to strip from source folder names",
+          aliases: ["-s"]
+        )
+        # Migrates emails from one account to another
+        # @return [void]
+        def migrate(source_email, destination_email)
+          non_logging_options = Imap::Backup::Logger.setup_logging(options)
+          CLI::Transfer.new(:migrate, source_email, destination_email, non_logging_options).run
+        end
+      end
+    end
+  end
+end

data/lib/imap/backup/cli/mirror.rb

@@ -0,0 +1,79 @@
+module Imap; end
+
+module Imap::Backup
+  # Processes parameters to run the `mirror` command via command-line parameters
+  module CLI::Mirror
+    include Thor::Actions
+    include CLI::Helpers
+
+    LONG_DESCRIPTION = <<~DESC.freeze
+      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.
+
+      If a folder list is configured for the SOURCE_EMAIL account,
+      only the folders indicated by the setting are copied.
+
+      First, it runs the download of the SOURCE_EMAIL account.
+      If the SOURCE_EMAIL account is **not** configured to be in 'mirror' mode,
+      a warning is printed.
+
+      When the mirror command is used, for each folder that is processed,
+      a new file is created alongside the normal backup files (.imap and .mbox)
+      This file has a '.mirror' extension. This file contains a mapping of
+      the known UIDs on the source account to those on the destination account.
+
+      Some configuration may be necessary, as follows:
+
+      #{CLI::Helpers::NAMESPACE_CONFIGURATION_DESCRIPTION}
+    DESC
+
+    def self.included(base)
+      base.class_eval do
+        desc(
+          "mirror SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
+          "(Deprecated) Keeps the DESTINATION_EMAIL account aligned with the SOURCE_EMAIL account"
+        )
+        long_desc LONG_DESCRIPTION
+        config_option
+        quiet_option
+        verbose_option
+        method_option(
+          "automatic-namespaces",
+          type: :boolean,
+          desc: "automatically choose delimiters and prefixes"
+        )
+        method_option(
+          "destination-delimiter",
+          type: :string,
+          desc: "the delimiter for destination folder names"
+        )
+        method_option(
+          "destination-prefix",
+          type: :string,
+          desc: "the prefix (namespace) to add to destination folder names",
+          aliases: ["-d"]
+        )
+        method_option(
+          "source-delimiter",
+          type: :string,
+          desc: "the delimiter for source folder names"
+        )
+        method_option(
+          "source-prefix",
+          type: :string,
+          desc: "the prefix (namespace) to strip from source folder names",
+          aliases: ["-s"]
+        )
+        # Keeps one email account in line with another
+        # @return [void]
+        def mirror(source_email, destination_email)
+          non_logging_options = Imap::Backup::Logger.setup_logging(options)
+          CLI::Transfer.new(:mirror, source_email, destination_email, non_logging_options).run
+        end
+      end
+    end
+  end
+end

data/lib/imap/backup/cli/transfer.rb

@@ -13,7 +13,7 @@ module Imap::Backup
     include CLI::Helpers
 
     # The possible values for the action parameter
-    ACTIONS = %i(migrate mirror).freeze
+    ACTIONS = %i(copy migrate mirror).freeze
 
     def initialize(action, source_email, destination_email, options)
       @action = action
@@ -39,14 +39,17 @@ module Imap::Backup
       raise "Unknown action '#{action}'" if !ACTIONS.include?(action)
 
       process_options!
-      prepare_mirror if action == :mirror
+      warn_if_source_account_is_not_in_mirror_mode if action == :mirror
+      run_backup if %i(copy mirror).include?(action)
 
       folders.each do |serializer, folder|
         case action
+        when :copy
+          Mirror.new(serializer, folder, reset: false).run
         when :migrate
           Migrator.new(serializer, folder, reset: reset).run
         when :mirror
-          Mirror.new(serializer, folder).run
+          Mirror.new(serializer, folder, reset: true).run
         end
       end
     end
@@ -123,9 +126,7 @@ module Imap::Backup
       self.source_prefix ||= ""
     end
 
-    def prepare_mirror
-      warn_if_source_account_is_not_in_mirror_mode
-
+    def run_backup
       CLI::Backup.new(config: config_path, accounts: source_email).run
     end
 

data/lib/imap/backup/cli.rb

@@ -12,6 +12,8 @@ module Imap::Backup
 
     autoload :Backup, "imap/backup/cli/backup"
     autoload :Local, "imap/backup/cli/local"
+    autoload :Migrate, "imap/backup/cli/migrate"
+    autoload :Mirror, "imap/backup/cli/mirror"
     autoload :Remote, "imap/backup/cli/remote"
     autoload :Restore, "imap/backup/cli/restore"
     autoload :Setup, "imap/backup/cli/setup"
@@ -22,28 +24,6 @@ module Imap::Backup
 
     include Helpers
 
-    NAMESPACE_CONFIGURATION_DESCRIPTION = <<~DESC.freeze
-      Some IMAP servers use namespaces (i.e. prefixes like "INBOX"),
-      while others, while others concatenate the names of subfolders
-      with a charater ("delimiter") other than "/".
-
-      In these cases there are two choices.
-
-      You can use the `--automatic-namespaces` option.
-      This will query the source and detination servers for their
-      namespace configuration and will adapt paths accordingly.
-      This option requires that both the source and destination
-      servers are available and work with the provided parameters
-      and authentication.
-
-      If automatic configuration does not work as desired, there are the
-      `--source-prefix=`, `--source-delimiter=`,
-      `--destination-prefix=` and `--destination-delimiter=` parameters.
-      To check what values you should use, check the output of the
-      `imap-backup remote namespaces EMAIL` command.
-    DESC
-    private_constant :NAMESPACE_CONFIGURATION_DESCRIPTION
-
     default_task :backup
 
     # Overrides {https://www.rubydoc.info/gems/thor/Thor%2FBase%2FClassMethods:start Thor's method}
@@ -94,91 +74,31 @@ module Imap::Backup
       Backup.new(non_logging_options).run
     end
 
-    desc "local SUBCOMMAND [OPTIONS]", "View local info"
-    subcommand "local", Local
-
     desc(
-      "migrate SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
-      "Uploads backed-up emails from account SOURCE_EMAIL to account DESTINATION_EMAIL"
+      "copy SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
+      "Copies emails from the SOURCE account to the DESTINATION account, avoiding duplicates"
     )
     long_desc <<~DESC
-      All emails which have been backed up for the "source account" (SOURCE_EMAIL) are
-      uploaded to the "destination account" (DESTINATION_EMAIL).
-
-      Some configuration may be necessary, as follows:
-
-      #{NAMESPACE_CONFIGURATION_DESCRIPTION}
-
-      Finally, if you want to delete existing emails in destination folders,
-      use the `--reset` option. In this case, all existing emails are
-      deleted before uploading the migrated emails.
-    DESC
-    config_option
-    quiet_option
-    verbose_option
-    method_option(
-      "automatic-namespaces",
-      type: :boolean,
-      desc: "automatically choose delimiters and prefixes"
-    )
-    method_option(
-      "destination-delimiter",
-      type: :string,
-      desc: "the delimiter for destination folder names"
-    )
-    method_option(
-      "destination-prefix",
-      type: :string,
-      desc: "the prefix (namespace) to add to destination folder names",
-      aliases: ["-d"]
-    )
-    method_option(
-      "reset",
-      type: :boolean,
-      desc: "DANGER! This option deletes all messages from destination folders before uploading",
-      aliases: ["-r"]
-    )
-    method_option(
-      "source-delimiter",
-      type: :string,
-      desc: "the delimiter for source folder names"
-    )
-    method_option(
-      "source-prefix",
-      type: :string,
-      desc: "the prefix (namespace) to strip from source folder names",
-      aliases: ["-s"]
-    )
-    # Migrates emails from one account to another
-    # @return [void]
-    def migrate(source_email, destination_email)
-      non_logging_options = Imap::Backup::Logger.setup_logging(options)
-      Transfer.new(:migrate, source_email, destination_email, non_logging_options).run
-    end
+      This command copies messages from the SOURCE_EMAIL account
+      to the DESTINATION_EMAIL account. It keeps track of copied
+      messages and avoids duplicate copies.
 
-    desc(
-      "mirror SOURCE_EMAIL DESTINATION_EMAIL [OPTIONS]",
-      "Keeps the DESTINATION_EMAIL account aligned with the SOURCE_EMAIL account"
-    )
-    long_desc <<~DESC
-      This command updates the DESTINATION_EMAIL account's folders to have the same contents
-      as those on the SOURCE_EMAIL account.
+      Any other messages that are present on the DESTINATION_EMAIL account
+      are not affected.
 
       If a folder list is configured for the SOURCE_EMAIL account,
       only the folders indicated by the setting are copied.
 
       First, it runs the download of the SOURCE_EMAIL account.
-      If the SOURCE_EMAIL account is **not** configured to be in 'mirror' mode,
-      a warning is printed.
 
-      When the mirror command is used, for each folder that is processed,
+      When the copy command is used, for each folder that is processed,
       a new file is created alongside the normal backup files (.imap and .mbox)
       This file has a '.mirror' extension. This file contains a mapping of
       the known UIDs on the source account to those on the destination account.
 
       Some configuration may be necessary, as follows:
 
-      #{NAMESPACE_CONFIGURATION_DESCRIPTION}
+      #{Helpers::NAMESPACE_CONFIGURATION_DESCRIPTION}
     DESC
     config_option
     quiet_option
@@ -210,13 +130,19 @@ module Imap::Backup
       desc: "the prefix (namespace) to strip from source folder names",
       aliases: ["-s"]
     )
-    # Keeps one email account in line with another
+    # Copies messages from one email account to another
     # @return [void]
-    def mirror(source_email, destination_email)
+    def copy(source_email, destination_email)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
-      Transfer.new(:mirror, source_email, destination_email, non_logging_options).run
+      Transfer.new(:copy, source_email, destination_email, non_logging_options).run
     end
 
+    desc "local SUBCOMMAND [OPTIONS]", "View local info"
+    subcommand "local", Local
+
+    include Migrate
+    include Mirror
+
     desc "remote SUBCOMMAND [OPTIONS]", "View info about online accounts"
     subcommand "remote", Remote
 

data/lib/imap/backup/client/default.rb

@@ -1,6 +1,7 @@
 require "forwardable"
 require "net/imap"
 
+require "imap/backup/email/provider"
 require "imap/backup/logger"
 
 module Imap; end
@@ -17,10 +18,8 @@ module Imap::Backup
       responses uid_fetch uid_search uid_store
     )
 
-    def initialize(server, account, options)
+    def initialize(account)
       @account = account
-      @options = options
-      @server = server
       @state = nil
     end
 
@@ -32,7 +31,10 @@ module Imap::Backup
 
       return [] if mailbox_lists.nil?
 
-      mailbox_lists.map { |ml| extract_name(ml) }
+      ignored_tags = provider.folder_ignore_tags
+      mailbox_lists.
+        select { |ml| ml.attr & ignored_tags == [] }.
+        map { |ml| extract_name(ml) }
     end
 
     # Logs in to the account on the IMAP server
@@ -83,8 +85,6 @@ module Imap::Backup
     private
 
     attr_reader :account
-    attr_reader :options
-    attr_reader :server
     attr_accessor :state
 
     def imap
@@ -100,17 +100,36 @@ module Imap::Backup
       account.password.gsub(/./, "x")
     end
 
+    def provider
+      @provider ||= Email::Provider.for_address(account.username)
+    end
+
+    def options
+      @options ||= provider.options.merge(account.connection_options || {})
+    end
+
+    def server
+      @server ||= account.server || provider.host
+    end
+
     # 6.3.8. LIST Command
     # An empty ("" string) mailbox name argument is a special request to
     # return the hierarchy delimiter and the root name of the name given
     # in the reference.
     def provider_root
-      @provider_root ||= begin
-        Logger.logger.debug "Fetching provider root"
-        root_info = imap.list("", "")[0]
-        Logger.logger.debug "Provider root is '#{root_info.name}'"
-        root_info.name
-      end
+      @provider_root ||=
+        if provider.root
+          Logger.logger.debug "Using fixed provider root '#{provider.root}'"
+          provider.root
+        else
+          Logger.logger.debug "Fetching provider root"
+          result = imap.list("", "")
+          raise "IMAP server did not return root folder for #{account.username}" if result.empty?
+
+          root_info = result[0]
+          Logger.logger.debug "Provider root is '#{root_info.name}'"
+          root_info.name
+        end
     end
   end
 end

data/lib/imap/backup/downloader.rb

@@ -13,13 +13,15 @@ module Imap::Backup
       @serializer = serializer
       @multi_fetch_size = multi_fetch_size
       @reset_seen_flags_after_fetch = reset_seen_flags_after_fetch
+      @folder_uids = nil
+      @serializer_uids = nil
       @uids = nil
     end
 
     # Runs the downloader
     # @return [void]
     def run
-      debug("#{serializer_uids.count} already messages already downloaded")
+      debug("#{serializer_uids.count} messages already downloaded")
       debug("#{folder_uids.count} messages on server")
       local_only_count = (serializer_uids - folder_uids).count
       if local_only_count.positive?
@@ -33,15 +35,7 @@ module Imap::Backup
 
       info("#{uids.count} new messages")
 
-      uids.each_slice(multi_fetch_size).with_index do |block, i|
-        multifetch_failed = download_block(block, i)
-        raise MultiFetchFailedError if multifetch_failed
-      end
-    rescue MultiFetchFailedError
-      @count = nil
-      @multi_fetch_size = 1
-      @uids = nil
-      retry
+      download
     rescue Net::IMAP::ByeResponseError
       folder.client.reconnect
       retry
@@ -54,6 +48,21 @@ module Imap::Backup
     attr_reader :multi_fetch_size
     attr_reader :reset_seen_flags_after_fetch
 
+    def download
+      block_count = (uids.count / multi_fetch_size.to_f).ceil
+      uids.each_slice(multi_fetch_size).with_index do |block, i|
+        debug("Downloading #{block.count} messages (block #{i + 1}/#{block_count})")
+        multifetch_failed = download_block(block, i)
+        raise MultiFetchFailedError if multifetch_failed
+      end
+    rescue MultiFetchFailedError
+      @multi_fetch_size = 1
+      @uids = nil
+      @folder_uids = nil
+      @serializer_uids = nil
+      retry
+    end
+
     def download_block(block, index)
       uids_and_bodies =
         if reset_seen_flags_after_fetch

data/lib/imap/backup/email/provider/apple_mail.rb

@@ -10,6 +10,11 @@ module Imap::Backup
       "imap.mail.me.com"
     end
 
+    # With Apple Mails's IMAP, passing "/" to list results in an empty list
+    def root
+      ""
+    end
+
     def sets_seen_flags_on_fetch?
       true
     end

data/lib/imap/backup/email/provider/base.rb

@@ -6,11 +6,22 @@ module Imap::Backup
 
   # Supplies defaults for email provider behaviour
   class Email::Provider::Base
+    # @return [Array<Symbol>] tags to ignore when listing folders
+    def folder_ignore_tags
+      []
+    end
+
     # @return [Hash] defaults for the Net::IMAP connection
     def options
       {port: 993, ssl: {min_version: OpenSSL::SSL::TLS1_2_VERSION}}
     end
 
+    # By default, we query the server for this value.
+    # It is only fixed for Apple Mail accounts.
+    # @return [String, nil] any fixed value to use when requesting the list of account folders
+    def root
+    end
+
     def sets_seen_flags_on_fetch?
       false
     end

data/lib/imap/backup/email/provider/gmail.rb

@@ -5,6 +5,11 @@ module Imap; end
 module Imap::Backup
   # Provides overrides for GMail accounts
   class Email::Provider::GMail < Email::Provider::Base
+    # https://imap-use.u.washington.narkive.com/RYMsOHTN/imap-protocol-status-on-a-noselect-mailbox
+    def folder_ignore_tags
+      [:Noselect]
+    end
+
     # @return [String] the GMail IMAP server host name
     def host
       "imap.gmail.com"

data/lib/imap/backup/mirror.rb

@@ -5,9 +5,10 @@ module Imap; end
 module Imap::Backup
   # Synchronises a folder between a source and destination
   class Mirror
-    def initialize(serializer, folder)
+    def initialize(serializer, folder, reset: false)
       @serializer = serializer
       @folder = folder
+      @reset = reset
     end
 
     # If necessary, reates the destination folder,
@@ -19,7 +20,7 @@ module Imap::Backup
     # @return [void]
     def run
       ensure_destination_folder
-      delete_destination_only_emails
+      delete_destination_only_emails if reset
       update_flags
       append_emails
       map.save
@@ -31,6 +32,7 @@ module Imap::Backup
 
     attr_reader :serializer
     attr_reader :folder
+    attr_reader :reset
 
     def ensure_destination_folder
       return if folder.exist?
@@ -90,7 +92,7 @@ module Imap::Backup
             destination: folder.uid_validity
           )
           if !map_ok
-            folder.clear
+            folder.clear if reset
             map.reset(
               source_uid_validity: serializer.uid_validity,
               destination_uid_validity: folder.uid_validity

data/lib/imap/backup/version.rb

@@ -2,11 +2,11 @@ module Imap; end
 
 module Imap::Backup
   # @private
-  MAJOR    = 15
+  MAJOR    = 16
   # @private
   MINOR    = 1
   # @private
-  REVISION = 3
+  REVISION = 0
   # @private
   PRE      = nil
   # The application version

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 15.1.3
+  version: 16.1.0
 platform: ruby
 authors:
 - Joe Yates
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -23,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mail
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -152,6 +181,8 @@ files:
 - lib/imap/backup/cli/helpers.rb
 - lib/imap/backup/cli/local.rb
 - lib/imap/backup/cli/local/check.rb
+- lib/imap/backup/cli/migrate.rb
+- lib/imap/backup/cli/mirror.rb
 - lib/imap/backup/cli/options.rb
 - lib/imap/backup/cli/remote.rb
 - lib/imap/backup/cli/restore.rb
@@ -161,7 +192,6 @@ files:
 - lib/imap/backup/cli/stats.rb
 - lib/imap/backup/cli/transfer.rb
 - lib/imap/backup/cli/utils.rb
-- lib/imap/backup/client/apple_mail.rb
 - lib/imap/backup/client/automatic_login_wrapper.rb
 - lib/imap/backup/client/default.rb
 - lib/imap/backup/configuration.rb
@@ -218,6 +248,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -232,7 +263,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.2.33
+signing_key:
 specification_version: 4
 summary: Backup GMail (or other IMAP) accounts to disk
 test_files: []

data/lib/imap/backup/client/apple_mail.rb

@@ -1,15 +0,0 @@
-require "imap/backup/client/default"
-
-module Imap; end
-
-module Imap::Backup
-  # Overrides default IMAP client behaviour for Apple Mail accounts
-  class Client::AppleMail < Client::Default
-    # With Apple Mails's IMAP, passing "/" to list
-    # results in an empty list
-    # @return [String] the value to use when requesting the list of account folders
-    def provider_root
-      ""
-    end
-  end
-end