rgrove/larch: Larch copies messages from one IMAP server to another. No longer maintained.

Utilization Examples¶ ↑

Larch is run from the command line. The next examples exhibit the best way to run Larch utilizing solely command line arguments, however you might also place these choices in a config file and run Larch with none arguments in the event you want. See the “Configuration” part beneath for extra particulars.

For an summary of all obtainable choices, run:

larch -h

At a minimal, you will need to specify a supply server and a vacation spot server within the type of IMAP URIs:

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

Larch will immediate you for the mandatory usernames and passwords, then sync the contents of the supply’s INBOX folder to the vacation spot’s INBOX folder.

To join utilizing SSL, specify a URI starting with imaps://:

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

If you would like to sync a selected folder aside from INBOX, specify the supply and vacation spot folders utilizing --from-folder and --to-folder. Folder names containing areas have to be enclosed in quotes:

larch --from imaps://mail.instance.com --to imaps://imap.gmail.com 
  --from-folder 'Despatched Mail' --to-folder 'Despatched Mail'

To sync all folders, use the --all possibility (or --all-subscribed in the event you solely need to sync subscribed folders):

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

By default Larch will create folders on the vacation spot server if they do not exist already. To stop this, add the --no-create-folder possibility:

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

You possibly can stop Larch from syncing a number of folders by utilizing the --exclude possibility, which accepts a number of arguments:

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

In case your exclusion listing is lengthy or complicated, create a textual content file with one exclusion sample per line and inform Larch to load it with the --exclude-file possibility:

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

The wildcard characters * and ? are supported in exclusion lists. You may additionally use a daily expression by enclosing a sample in ahead slashes, so the earlier instance could possibly be achieved with the sample /(Spam|Trash|Drafts|[Gmail]/.*)/

Configuration¶ ↑

Whereas it is attainable to regulate Larch fully from the command line, this may be inconvenient if it’s essential to specify lots of choices or in the event you run Larch incessantly and might’t all the time bear in mind which choices to make use of. Utilizing a configuration file can simplify issues.

By default, Larch appears to be like for a config file at ~/.larch/config.yaml and makes use of it if discovered. It’s possible you’ll specify a customized config file utilizing the --config command line possibility.

The Larch configuration file is a straightforward YAML file which will include a number of sections, every with a unique set of choices, in addition to a particular default part. The choices within the default part shall be used except they’re overridden both in one other config part or on the command line.

Instance¶ ↑

Here is a pattern Larch config file:

default:
  all-subscribed: true # Copy all subscribed folders by default

# Copy mail from Gmail to my server, excluding stuff I do not need.
gmail to my server:
  from: imaps://imap.gmail.com
  from-user: instance
  from-pass: secret

  to: imaps://mail.instance.com
  to-user: instance
  to-pass: secret

  exclude:
    - "[Gmail]/Despatched Mail"
    - "[Gmail]/Spam"
    - "[Gmail]/Trash"

# Copy mail from my INBOX to Gmail's INBOX
my inbox to gmail inbox:
  all-subscribed: false

  from: imaps://mail.instance.com
  from-folder: INBOX
  from-user: instance
  from-pass: secret

  to: imaps://imap.gmail.com
  to-folder: INBOX
  to-user: instance
  to-pass: secret

This file comprises three sections. The choices from default shall be utilized in all different sections as properly except they’re overridden.

To specify which config part you need Larch to make use of, simply go its title on the command line (use quotes if the title comprises areas):

larch 'gmail to my server'

When you specify extra command line choices, they will override choices within the config file:

larch 'gmail to my server' --from-user anotheruser

Operating Larch with no command line arguments will trigger the default part for use. With the instance above, this may lead to an error for the reason that default part does not include the required from and to choices, however in the event you solely want to make use of Larch with a single configuration, you may use the default part for every part and save your self some typing on the command line.

Server Compatibility¶ ↑

Larch ought to work properly with any server that correctly helps IMAP4rev1, and does its greatest to get together with servers which have buggy, unreliable, or incomplete IMAP implementations.

Larch has been examined on and is thought to work properly with the next IMAP servers:

• Dovecot

• Gmail

• Microsoft Alternate 2003

The next servers are recognized to work, however with caveats:

The next servers don’t work properly with Larch:

Gmail Quirks¶ ↑

Gmail’s IMAP implementation is quirky. Larch does its greatest to work round these quirks at any time when attainable, however right here are some things to be careful for:

“Some messages couldn’t be FETCHed” error¶ ↑

This error signifies {that a} message on Gmail is corrupt, and Gmail itself is unable to learn it. The message will proceed to point out up within the mailbox, however all makes an attempt to entry it by way of IMAP, POP, or the Gmail net interface will lead to errors. Larch will attempt to skip these messages and proceed processing others if attainable.

It is not clear how this corruption happens or precisely what sort of corruption causes these errors, though in each case I am conscious of, the corrupt message has originated exterior of Gmail (Gmail itself doesn’t corrupt the message). There may be presently no recognized answer for this downside aside from deleting the corrupted messages.

Folder names can not include main or trailing whitespace¶ ↑

Most IMAP servers permit folder names to include main and trailing whitespace, corresponding to “ folder ”. Gmail doesn’t. When copying folders to Gmail, Larch will mechanically take away main and trailing whitespace in folder names to forestall errors.

Yahoo! Mail Quirks¶ ↑

Yahoo! does not formally help IMAP entry for common utilization, however Larch is in a position to hook up with imap.mail.yahoo.com and imap-ssl.mail.yahoo.com by utilizing a reasonably well-known trick. That stated, as with something difficult, there are caveats.

No hierarchical folders¶ ↑

Much like Gmail, Yahoo! Mail does not permit hierarchical (nested) folders. When you attempt to copy a folder hierarchy to Yahoo!, it can work, however you may find yourself with a set of folders named “folder” and “folder.subfolder” reasonably than seeing “subfolder” as an precise subfolder of “folder”.

No customized flags¶ ↑

Yahoo! Mail IMAP does not help customized message flags, such because the tags and junk/not junk flags utilized by Thunderbird. When transferring messages with customized flags to a Yahoo! Mail IMAP account, the customized flags shall be misplaced.

Right here there be dragons¶ ↑

Larch’s help for Yahoo! Mail could be very new and really calmly examined. Given its newness and the truth that Yahoo!’s IMAP gateway is not official, there are more likely to be different quirks we’re not but conscious of. There’s additionally no assure that Yahoo! will not shut down its IMAP gateway, deprecate the trick Larch makes use of to attach, or simply outright block Larch. Use at your individual danger.

Recognized Points¶ ↑

• Larch makes use of Ruby’s Internet::IMAP normal library for all IMAP operations. Whereas Internet::IMAP is usually a really stable library, it comprises a bug that may trigger a impasse to happen if a connection drops unexpectedly (both on account of community points or as a result of the server closed the connection with out warning) when the server has already begun sending a response and Internet::IMAP is ready to obtain extra knowledge. If this occurs, Internet::IMAP will proceed ready ceaselessly with out passing management again to Larch, and you have to to manually kill and restart Larch.

  Internet::IMAP in Ruby 1.eight has additionally been recognized to hold when it could actually’t parse a server response, both as a result of the response itself is malformed or due to a bug in Internet::IMAP’s parser. That is uncommon, but it surely occurs. Sadly there’s nothing Larch can do about this.

• The Ruby bundle on Debian, Ubuntu, and another Debian-based Linux distributions does not embrace the OpenSSL normal library. When you see an error like uninitialized fixed Larch::IMAP::OpenSSL (NameError) when working Larch, it’s possible you’ll want to put in the libopenssl-ruby bundle. Please be at liberty to complain to the maintainer of your distribution’s Ruby packages.

The Larch mailing listing is the most effective place for questions, feedback, and dialogue about Larch. You possibly can be part of the listing or view the archives at teams.google.com/group/larch

First-time senders to the listing are moderated to forestall spam, so there could also be a delay earlier than your first message exhibits up.

Contributors¶ ↑

Larch was created and is maintained by Ryan Grove .

The next beautiful individuals have additionally contributed to Larch:

• Torey Heinz

• Edgardo Hames

• Andrew Hobson

• Justin Mazzi

The Larch::IMAP class borrows closely from Sup by William Morgan, the supply code of which ought to be required studying in the event you’re doing something with IMAP in Ruby.

Larch makes use of the wonderful Trollop command-line possibility parser (additionally by William Morgan) and the HighLine command-line IO library (by James Edward Grey II).

Copyright © 2013 Ryan Grove

Licensed below the GNU Basic Public License model 2.0.

This program is free software program; you’ll be able to redistribute it and/or modify it below the phrases of model 2.Zero of the GNU Basic Public License as printed by the Free Software program Basis.

This program is distributed within the hope that it is going to be helpful, however WITHOUT ANY WARRANTY; with out even the implied guarantee of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Basic Public License for extra particulars.

You must have acquired a replica of the GNU Basic Public License together with this program; if not, go to www.gnu.org/licenses/old-licenses/gpl-2.0.txt or write to the Free Software program Basis, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.