imap-backup 8.0.1 → 9.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e9bb0714badd71868da39868ccf19337cab655b34a0b75e19fa4022efdba7e1
-  data.tar.gz: 077b1accfaa164424e49ed98913124a04c0d5014eb52b2b79676ec41d038c942
+  metadata.gz: 3a95742a7ae3b07a12f7cb95d50bcea360530ee351edbca8d9b93e5c4579090a
+  data.tar.gz: 9d7d43ba0f44f13a19272214dfe8ca265c72f7d1173ccf67c4d4a873de007a81
 SHA512:
-  metadata.gz: b9475fd7fb40295af794ad94572b8df8733a26a75c2045a0dd26feec655391796206c5d6f777b2255e3ddd5f5658c1c59186c8b63026650e1312eebf90e4c2ec
-  data.tar.gz: 53ae3936d98b3b88b1127a632d5933feaf42429b2917efd8442c3963631ef12ebb5498546b25b014eedcbe7e255cb68ae40520d1ce0f7f67604e8158d2530862
+  metadata.gz: 155eeb475d56b03bc8012fc8b9b2882fbd8bcaad4366ee2119952f710de79d94a6709c81185ccc49b4f20f6d333523272de4cfa3742c1ff05f797830d1cb916e
+  data.tar.gz: dc6c0ce95c22c81512eb71791f6a75ecc8fe35f011e48fd0d68266771fac96f234664f22316fd1e98fbfc93397713f60375555442577dc0977eedcabfc2cf1ea

data/README.md

@@ -7,18 +7,20 @@
 
 Backup, restore and migrate email accounts.
 
-The backups can then be restored, used to migrate to another service,
-inspected or exported.
+# Modes
 
-  * [Source Code]
-  * [Code Documentation]
-  * [Rubygem]
-  * [CI Status]
+There are two types of backups:
 
-[Source Code]: https://github.com/joeyates/imap-backup "Source code at GitHub"
-[Code Documentation]: https://rubydoc.info/gems/imap-backup/frames "Code Documentation at Rubydoc.info"
-[Rubygem]: https://rubygems.org/gems/imap-backup "Ruby gem at rubygems.org"
-[CI Status]: https://github.com/joeyates/imap-backup/actions/workflows/main.yml
+* Keep all (the default) - progressively saves a local copy of all emails,
+* Mirror - adds and deletes emails from the local copy to keep it up to date with the account.
+
+# 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.
+* Restore - push the local copy back to the original account.
+
+See below for a [full list of commands](#Commands).
 
 # Installation
 
@@ -67,6 +69,9 @@ imap-backup
 
 Alternatively, add it to your crontab.
 
+Backups can also be inspected, for example via [local show](docs/commands/local-show.md)
+and exported via [utils export-to-thunderbird](docs/commands/utils-export-to-thunderbird.md).
+
 # Commands
 
 * [backup](docs/commands/backup.md)
@@ -99,7 +104,7 @@ imap-backup help COMMAND
 If you have problems:
 
 1. ensure that you have the latest release,
-2. turn on debugging output via the `imap-backup setup` main menu.
+2. run `imap-backup` with the `-v` or `--verbose` parameter.
 
 # Development
 
@@ -108,3 +113,13 @@ on development and testing.
 
 See [the CHANGELOG](./CHANGELOG.md) to a list of changes that have been
 made in each release.
+
+* [Source Code]
+* [Code Documentation]
+* [Rubygem]
+* [CI Status]
+
+[Source Code]: https://github.com/joeyates/imap-backup "Source code at GitHub"
+[Code Documentation]: https://rubydoc.info/gems/imap-backup/frames "Code Documentation at Rubydoc.info"
+[Rubygem]: https://rubygems.org/gems/imap-backup "Ruby gem at rubygems.org"
+[CI Status]: https://github.com/joeyates/imap-backup/actions/workflows/main.yml

data/docs/delimiters-and-prefixes.md

@@ -0,0 +1,16 @@
+# Delimiters and Prefixes
+
+A simple folder name is `Friends`.
+
+Most email servers allow you to put folders inside other folders.
+
+On most email servers, the parts of a folder's name are separated with a `/` character.
+So you might have `People/Friends`.
+
+On the other hand, some email servers use a `.`, giving `People.Friends`.
+
+Some email servers keep most email in a parent folder, often `INBOX`, so the above folder
+would be `INBOX/People/Friends`.
+
+The `migrate` and `mirror` commands provide options to help "translate" between
+the behaviour of the source and destination servers.

data/docs/restore.md

@@ -25,6 +25,4 @@ is already on the server is skipped.
 
 ## How do I restore to a different service?
 
-1. Run setup and add the new server, (but don't run any backups),
-2. Rename of the existing backup directory to match the new email address,
-3. Run the restore.
+It is best to use the `migrate` command in this case.

data/docs/setup.md

@@ -2,4 +2,4 @@
 
 ## Set the server for a Google Apps account
 
-Use imap.gmail.com
+Use `imap.gmail.com` as the 'server' setting.

data/imap-backup.gemspec

@@ -22,8 +22,8 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = ">= 2.6"
 
   gem.add_runtime_dependency "highline"
-  gem.add_runtime_dependency "mail"
-  gem.add_runtime_dependency "net-imap"
+  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 "rake"

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

@@ -154,8 +154,9 @@ module Imap::Backup
     end
 
     def extract_uid(response)
-      @uid_validity, uid = response.data.code.data.split.map(&:to_i)
-      uid
+      uid_data = response.data.code.data
+      @uid_validity = uid_data.uidvalidity
+      uid_data.assigned_uids.first
     end
 
     def utf7_encoded_name

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

@@ -0,0 +1,96 @@
+module Imap::Backup
+  class CLI::FolderEnumerator
+    attr_reader :destination
+    attr_reader :destination_delimiter
+    attr_reader :source
+    attr_reader :source_delimiter
+
+    def initialize(
+      destination:,
+      source:,
+      destination_delimiter: "/",
+      destination_prefix: "",
+      source_delimiter: "/",
+      source_prefix: ""
+    )
+      @destination = destination
+      @destination_delimiter = destination_delimiter
+      @destination_prefix = destination_prefix
+      @source = source
+      @source_delimiter = source_delimiter
+      @source_prefix = source_prefix
+    end
+
+    def each
+      return enum_for(:each) if !block_given?
+
+      glob = File.join(source_local_path, "**", "*.imap")
+      Pathname.glob(glob) do |path|
+        name = source_folder_name(path)
+        serializer = Serializer.new(source_local_path, name)
+        folder = destination_folder_for(name)
+        yield serializer, folder
+      end
+    end
+
+    private
+
+    def destination_prefix_clipped
+      @destination_prefix_clipped ||=
+        if @destination_prefix.end_with?(destination_delimiter)
+          @destination_prefix[0..-2]
+        else
+          @destination_prefix
+        end
+    end
+
+    def source_prefix_clipped
+      @source_prefix_clipped ||=
+        if @source_prefix.end_with?(source_delimiter)
+          @source_prefix[0..-2]
+        else
+          @source_prefix
+        end
+    end
+
+    def destination_folder_for(name)
+      parts = name.split(source_delimiter)
+      no_source_prefix =
+        if source_prefix_clipped != "" && parts.first == source_prefix_clipped
+          parts[1..]
+        else
+          parts
+        end
+
+      with_destination_prefix =
+        if destination_prefix_clipped && destination_prefix_clipped != ""
+          no_source_prefix.unshift(destination_prefix_clipped)
+        else
+          no_source_prefix
+        end
+
+      destination_name = with_destination_prefix.join(destination_delimiter)
+
+      Account::Folder.new(
+        destination.connection,
+        destination_name
+      )
+    end
+
+    def source_local_path
+      source.local_path
+    end
+
+    def source_folder_name(imap_pathname)
+      base = Pathname.new(source_local_path)
+      imap_name = imap_pathname.relative_path_from(base).to_s
+      dir = File.dirname(imap_name)
+      stripped = File.basename(imap_name, ".imap")
+      if dir == "."
+        stripped
+      else
+        File.join(dir, stripped)
+      end
+    end
+  end
+end

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

@@ -1,3 +1,4 @@
+require "imap/backup/cli/folder_enumerator"
 require "imap/backup/migrator"
 
 module Imap::Backup
@@ -5,10 +6,12 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    attr_reader :destination_delimiter
     attr_reader :destination_email
     attr_reader :destination_prefix
     attr_reader :config_path
     attr_reader :reset
+    attr_reader :source_delimiter
     attr_reader :source_email
     attr_reader :source_prefix
 
@@ -16,15 +19,19 @@ module Imap::Backup
       source_email,
       destination_email,
       config: nil,
+      destination_delimiter: "/",
       destination_prefix: "",
       reset: false,
+      source_delimiter: "/",
       source_prefix: ""
     )
       super([])
+      @destination_delimiter = destination_delimiter
       @destination_email = destination_email
       @destination_prefix = destination_prefix
       @config_path = config
       @reset = reset
+      @source_delimiter = source_delimiter
       @source_email = source_email
       @source_prefix = source_prefix
     end
@@ -51,62 +58,28 @@ module Imap::Backup
         @config ||= load_config(config: config_path)
       end
 
-      def destination_account
-        config.accounts.find { |a| a.username == destination_email }
+      def enumerator_options
+        {
+          destination: destination_account,
+          destination_delimiter: destination_delimiter,
+          destination_prefix: destination_prefix,
+          source: source_account,
+          source_delimiter: source_delimiter,
+          source_prefix: source_prefix
+        }
       end
 
       def folders
-        return enum_for(:folders) if !block_given?
-
-        glob = File.join(source_local_path, "**", "*.imap")
-        Pathname.glob(glob) do |path|
-          name = source_folder_name(path)
-          serializer = Serializer.new(source_local_path, name)
-          folder = folder_for(name)
-          yield serializer, folder
-        end
+        CLI::FolderEnumerator.new(**enumerator_options)
       end
 
-      def folder_for(source_folder)
-        no_source_prefix =
-          if source_prefix != "" && source_folder.start_with?(source_prefix)
-            source_folder.delete_prefix(source_prefix)
-          else
-            source_folder.to_s
-          end
-
-        with_destination_prefix =
-          if destination_prefix && destination_prefix != ""
-            destination_prefix + no_source_prefix
-          else
-            no_source_prefix
-          end
-
-        Account::Folder.new(
-          destination_account.connection,
-          with_destination_prefix
-        )
-      end
-
-      def source_local_path
-        source_account.local_path
+      def destination_account
+        config.accounts.find { |a| a.username == destination_email }
       end
 
       def source_account
         config.accounts.find { |a| a.username == source_email }
       end
-
-      def source_folder_name(imap_pathname)
-        base = Pathname.new(source_local_path)
-        imap_name = imap_pathname.relative_path_from(base).to_s
-        dir = File.dirname(imap_name)
-        stripped = File.basename(imap_name, ".imap")
-        if dir == "."
-          stripped
-        else
-          File.join(dir, stripped)
-        end
-      end
     end
   end
 end

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

@@ -1,3 +1,4 @@
+require "imap/backup/cli/folder_enumerator"
 require "imap/backup/mirror"
 
 module Imap::Backup
@@ -5,9 +6,11 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    attr_reader :destination_delimiter
     attr_reader :destination_email
     attr_reader :destination_prefix
     attr_reader :config_path
+    attr_reader :source_delimiter
     attr_reader :source_email
     attr_reader :source_prefix
 
@@ -15,13 +18,17 @@ module Imap::Backup
       source_email,
       destination_email,
       config: nil,
+      destination_delimiter: "/",
       destination_prefix: "",
+      source_delimiter: "/",
       source_prefix: ""
     )
       super([])
+      @destination_delimiter = destination_delimiter
       @destination_email = destination_email
       @destination_prefix = destination_prefix
       @config_path = config
+      @source_delimiter = source_delimiter
       @source_email = source_email
       @source_prefix = source_prefix
     end
@@ -61,62 +68,28 @@ module Imap::Backup
         @config = load_config(config: config_path)
       end
 
-      def destination_account
-        config.accounts.find { |a| a.username == destination_email }
+      def enumerator_options
+        {
+          destination: destination_account,
+          destination_delimiter: destination_delimiter,
+          destination_prefix: destination_prefix,
+          source: source_account,
+          source_delimiter: source_delimiter,
+          source_prefix: source_prefix
+        }
       end
 
       def folders
-        return enum_for(:folders) if !block_given?
-
-        glob = File.join(source_local_path, "**", "*.imap")
-        Pathname.glob(glob) do |path|
-          name = source_folder_name(path)
-          serializer = Serializer.new(source_local_path, name)
-          folder = folder_for(name)
-          yield serializer, folder
-        end
-      end
-
-      def folder_for(source_folder)
-        no_source_prefix =
-          if source_prefix != "" && source_folder.start_with?(source_prefix)
-            source_folder.delete_prefix(source_prefix)
-          else
-            source_folder.to_s
-          end
-
-        with_destination_prefix =
-          if destination_prefix && destination_prefix != ""
-            destination_prefix + no_source_prefix
-          else
-            no_source_prefix
-          end
-
-        Account::Folder.new(
-          destination_account.connection,
-          with_destination_prefix
-        )
+        CLI::FolderEnumerator.new(**enumerator_options)
       end
 
-      def source_local_path
-        source_account.local_path
+      def destination_account
+        config.accounts.find { |a| a.username == destination_email }
       end
 
       def source_account
         config.accounts.find { |a| a.username == source_email }
       end
-
-      def source_folder_name(imap_pathname)
-        base = Pathname.new(source_local_path)
-        imap_name = imap_pathname.relative_path_from(base).to_s
-        dir = File.dirname(imap_name)
-        stripped = File.basename(imap_name, ".imap")
-        if dir == "."
-          stripped
-        else
-          File.join(dir, stripped)
-        end
-      end
     end
   end
 end

data/lib/imap/backup/cli.rb

@@ -69,9 +69,12 @@ module Imap::Backup
       All emails which have been backed up for the "source account" (SOURCE_EMAIL) are
       uploaded to the "destination account" (DESTINATION_EMAIL).
 
-      When one or other account has namespaces (i.e. prefixes like "INBOX."),
+      When one or other account has namespaces (i.e. prefixes like "INBOX"),
       use the `--source-prefix=` and/or `--destination-prefix=` options.
 
+      When one or other account uses a delimiter other than `/` (i.e. `.`),
+      use the `--source-delimiter=` and/or `--destination-delimiter=` options.
+
       Usually, you should migrate to an account with empty folders.
 
       Before migrating each folder, `imap-backup` checks if the destination
@@ -86,6 +89,11 @@ module Imap::Backup
     config_option
     quiet_option
     verbose_option
+    method_option(
+      "destination-delimiter",
+      type: :string,
+      desc: "the delimiter for destination folder names"
+    )
     method_option(
       "destination-prefix",
       type: :string,
@@ -98,6 +106,11 @@ module Imap::Backup
       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,
@@ -132,12 +145,22 @@ module Imap::Backup
     config_option
     quiet_option
     verbose_option
+    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,

data/lib/imap/backup/version.rb

@@ -1,9 +1,9 @@
 module Imap; end
 
 module Imap::Backup
-  MAJOR    = 8
+  MAJOR    = 9
   MINOR    = 0
-  REVISION = 1
-  PRE      = nil
+  REVISION = 0
+  PRE      = "rc1".freeze
   VERSION  = [MAJOR, MINOR, REVISION, PRE].compact.map(&:to_s).join(".")
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 8.0.1
+  version: 9.0.0.rc1
 platform: ruby
 authors:
 - Joe Yates
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-24 00:00:00.000000000 Z
+date: 2022-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -28,30 +28,30 @@ dependencies:
   name: mail
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.7.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.7.1
 - !ruby/object:Gem::Dependency
   name: net-imap
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.3.2
 - !ruby/object:Gem::Dependency
   name: net-smtp
   requirement: !ruby/object:Gem::Requirement
@@ -218,6 +218,7 @@ files:
 - README.md
 - bin/imap-backup
 - docs/configuration.md
+- docs/delimiters-and-prefixes.md
 - docs/development.md
 - docs/restore.md
 - docs/setup.md
@@ -240,6 +241,7 @@ files:
 - lib/imap/backup/account/folder.rb
 - lib/imap/backup/cli.rb
 - lib/imap/backup/cli/backup.rb
+- lib/imap/backup/cli/folder_enumerator.rb
 - lib/imap/backup/cli/helpers.rb
 - lib/imap/backup/cli/local.rb
 - lib/imap/backup/cli/migrate.rb
@@ -299,9 +301,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.3.7
 signing_key: