Larch

Larch is a tool to copy messages from one IMAP server to another quickly and safely. It’s smart enough not to copy messages that already exist on the destination and robust enough to deal with ornery or misbehaving servers.

Larch is particularly well-suited for copying email to, from, or between Gmail accounts.

Author

Ryan Grove ([email protected])

Version

1.0.2 (2009-08-05)

Copyright

Copyright © 2009 Ryan Grove. All rights reserved.

License

GPL 2.0 (opensource.org/licenses/gpl-2.0.php)

Website

github.com/rgrove/larch

Installation

Install Larch via RubyGems:

gem install larch

Usage

larch --from <uri> --to <uri> [options]

Required:
     --from, -f <s>:   URI of the source IMAP server.
       --to, -t <s>:   URI of the destination IMAP server.

Copy Options:
              --all:   Copy all folders recursively
   --all-subscribed:   Copy all subscribed folders recursively
     --exclude <s+>:   List of mailbox names/patterns that shouldn't be
                       copied
 --exclude-file <s>:   Filename containing mailbox names/patterns that
                       shouldn't be copied
  --from-folder <s>:   Source folder to copy from (default: INBOX)
    --from-pass <s>:   Source server password (default: prompt)
    --from-user <s>:   Source server username (default: prompt)
    --to-folder <s>:   Destination folder to copy to (default: INBOX)
      --to-pass <s>:   Destination server password (default: prompt)
      --to-user <s>:   Destination server username (default: prompt)

General Options:
      --dry-run, -n:   Don't actually make any changes.
        --fast-scan:   Use a faster (but less accurate) method to scan
                       mailboxes. This may result in messages being
                       re-copied.
  --max-retries <i>:   Maximum number of times to retry after a recoverable
                       error (default: 3)
 --no-create-folder:   Don't create destination folders that don't already
                       exist
    --ssl-certs <s>:   Path to a trusted certificate bundle to use to
                       verify server SSL certificates
       --ssl-verify:   Verify server SSL certificates
--verbosity, -V <s>:   Output verbosity: debug, info, warn, error, or fatal
                       (default: info)
      --version, -v:   Print version and exit
         --help, -h:   Show this message

Examples

Larch is run from the command line. At a minimum, you must specify a source server and a destination server in the form of IMAP URIs. You may also specify one or more options:

larch --from <uri> --to <uri> [options]

For an overview of all available command-line options, run:

larch --help

Specify a source server and a destination server and Larch will prompt you for the necessary usernames and passwords, then sync the contents of the source’s INBOX folder to the destination:

larch --from imap://mail.example.com --to imap://imap.gmail.com

To connect using SSL, specify a URI beginning with imaps://:

larch --from imaps://mail.example.com --to imaps://imap.gmail.com

If you’d like to sync a specific folder other than INBOX, specify the source and destination folders using --from-folder and --to-folder:

larch --from imaps://mail.example.com --to imaps://imap.gmail.com \
  --from-folder "Sent Mail" --to-folder "Sent Mail"

To sync all folders, use the --all option (or --all-subscribed if you only want to sync subscribed folders):

larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all

By default Larch will create folders on the destination server if they don’t already exist. To prevent this, add the --no-create-folder option:

larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \
  --no-create-folder

You can prevent Larch from syncing one or more folders by using the --exclude option:

larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \
  --exclude Spam Trash Drafts "[Gmail]/*"

If your exclusion list is long or complex, create a text file with one exclusion pattern per line and tell Larch to load it with the --exclude-file option:

larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \
  --exclude-file exclude.txt

The wildcard characters * and ? are supported in exclusion lists. You can also use a regular expression by enclosing a pattern in forward slashes, so the previous example could be achieved with the pattern /(Spam|Trash|Drafts|\[Gmail\]\/.*)/

Server Compatibility

Larch should work well with any server that properly supports IMAP4rev1, and does its best to get along with servers that have buggy, unreliable, or incomplete IMAP implementations.

Larch has been tested on and is known to work well with the following IMAP servers:

  • Dovecot

  • Gmail

  • Microsoft Exchange 2003

The following servers do not work well with Larch:

  • BlitzMail - Buggy server implementation; fails to properly quote or escape some IMAP responses, which can cause Larch to hang waiting for a terminating character that will never arrive.

Known Issues

  • Larch uses Ruby’s Net::IMAP standard library for all IMAP operations. While Net::IMAP is generally a very solid library, it contains a bug that can cause a deadlock to occur if a connection drops unexpectedly (either due to network issues or because the server closed the connection without warning) when the server has already begun sending a response and Net::IMAP is waiting to receive more data.

    If this happens, Net::IMAP will continue waiting forever without passing control back to Larch, and you will need to manually kill and restart Larch.

  • The Ruby package on Debian, Ubuntu, and some other Debian-based Linux distributions doesn’t include the OpenSSL standard library. If you see an error like uninitialized constant Larch::IMAP::OpenSSL (NameError) when running Larch, you may need to install the libopenssl-ruby package. Please feel free to complain to the maintainer of your distribution’s Ruby packages.

Support

The Larch mailing list is the best place for questions, comments, and discussion about Larch. You can join the list or view the archives at groups.google.com/group/larch

Credit

The Larch::IMAP class borrows heavily from Sup by William Morgan, the source code of which should be required reading if you’re doing anything with IMAP in Ruby.

Larch uses the excellent Trollop command-line option parser (also by William Morgan) and the HighLine command-line IO library (by James Edward Gray II).

License

Copyright © 2009 Ryan Grove <[email protected]>

Licensed under the GNU General Public License version 2.0.

This program is free software; you can redistribute it and/or modify it under the terms of version 2.0 of the GNU General Public License as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, visit www.gnu.org/licenses/old-licenses/gpl-2.0.txt or write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.