.de URL \\$2 \(laURL: \\$1 \(ra\\$3 .. .if \n[.g] .mso www.tmac .TH LARCH 1 .SH NAME larch \- copy messages from one IMAP server to another .SH SYNOPSIS .B larch [\fIoptions\fR] .PP .B larch [\fB\-\-from\fR \fIURI\fR] [\fB\-\-to\fR \fIURI\fR] .SH DESCRIPTION .B 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 interruptions caused by flaky connections or misbehaving servers. .PP .B Larch is particularly well-suited for copying email to, from, or between Gmail accounts. .SH OPTIONS .SS Server options .TP .BR \-\-from ", " \-f " " \fIURI\fR URI of the source IMAP server. .TP .BR \-\-from\-folder ", " \-F " " \fIFOLDER\fR Source folder to copy from. Default is INBOX. .TP .BR \-\-from\-pass ", " \-p " " \fIPASSWD\fR Source server password. Default is to prompt the user. .TP .BR \-\-from\-user ", " \-u " " \fIUSER\fR Source server username. Default is to prompt the user. .TP .BR \-\-to ", " \-t " " \fIURI\fR URI of the destination IMAP server. .TP .BR \-\-to\-folder ", " \-T " " \fIFOLDER\fR Destination folder to copy to. Default is INBOX. .TP .BR \-\-to\-pass ", " \-P " " \fIPASSWD\fR Destination server password. Default is to prompt the user. .TP .BR \-\-to\-user ", " \-U " " \fIUSER\fR Destination server username. Default is to prompt the user. .SS Copy options .TP .BR \-\-all ", " \-a Copy all folders recursively. .TP .BR \-\-all\-subscribed ", " \-s Copy all subscribed folders recursively. .TP .BR \-\-delete ", " \-d Delete messages from the source after copying them, or if they already exist at the destination. .TP .BR \-\-exclude " " \fIPATTERN\fR " [ " \fIPATTERN\fR "... ]" List of mailbox names/patterns that shouldn't be copied. .TP .BR \-\-exclude\-file " " \fIFILE\fR Filename containing mailbox names/patterns that shouldn't be copied. .TP .BR \-\-expunge ", " \-x Expunge deleted messages from the source. .TP .BR \-\-sync\-flags ", " \-S Sync message flags from the source to the destination for messages that already exist at the destination. .SS General options .TP .BR \-\-config ", " \-c " " \fIFILE\fR Specify a non\-default config file to use. Default is ~/.larch/config.yaml. .TP .BR \-\-database " " \fIFILE\fR Specify a non\-default message database to use. Default is ~/.larch/larch.db. .TP .BR \-\-dry\-run ", " \-n Don't actually make any changes. .TP .BR \-\-max\-retries " " \fINUM\fR Maximum number of times to retry after a recoverable error. Default is 3. .TP .BR \-\-no\-create\-folder Don't create destination folders that don't already exist. .TP .BR \-\-ssl\-certs " " \fIFILE\fR Path to a trusted certificate bundle to use to verify server SSL certificates. .TP .BR \-\-ssl\-verify Verify server SSL certificates. .TP .BR \-\-verbosity ", " \-V " " \fISTR\fR Output verbosity: debug, info, warn, error, or fatal. Default is info. .TP .BR \-\-version ", " \-v Print version and exit. .TP .BR \-\-help ", " \-h Show a help message. .SH CONFIGURATION While it's possible to control \fBLarch\fR entirely from the command line, this can be inconvenient if you need to specify a lot of options or if you run \fBLarch\fR frequently and can't always remember which options to use. Using a configuration file can simplify things. .PP By default, \fBLarch\fR looks for a config file at \fB~/.larch/config.yaml\fR and uses it if found. You may specify a custom config file using the \fB\-\-config\fR command line option. .PP The \fBLarch\fR configuration file is a simple .URL http://yaml.org/ YAML file that may contain multiple sections, each with a different set of options, as well as a special \fIdefault\fR section. The options in the \fIdefault\fR section will be used unless they're overridden either in another config section or on the command line. .PP Here's a sample Larch config file: .PP .nf .RS # Copy all subscribed folders by default default: all-subscribed: true # Copy mail from Gmail to my server, excluding stuff I don't want. gmail to my server: from: imaps://imap.gmail.com from-user: example from-pass: secret to: imaps://mail.example.com to-user: example to-pass: secret exclude: - "[Gmail]/Sent 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.example.com from-folder: INBOX from-user: example from-pass: secret to: imaps://imap.gmail.com to-folder: INBOX to-user: example to-pass: secret .RE .fi .PP This file contains three sections. The options from \fIdefault\fR will be used in all other sections as well unless they're overridden. .PP To specify which config section you want Larch to use, just pass its name on the command line (use quotes if the name contains spaces): .PP .nf .RS larch \(aqgmail to my server\(aq .RE .fi .PP If you specify additional command line options, they'll override options in the config file: .PP .nf .RS larch \(aqgmail to my server\(aq --from-user anotheruser .RE .fi .PP Running Larch with no command line arguments will cause the \fIdefault\fR section to be used. With the example above, this will result in an error since the \fIdefault\fR section doesn't contain the required \fIfrom\fR and \fIto\fR options, but if you only need to use Larch with a single configuration, you could use the \fIdefault\fR section for everything and save yourself some typing on the command line. .SH FILES .I ~/.larch/config.yaml .SH NOTES .SS Server compatibility Larch should work well with any server that properly supports .URL http://tools.ietf.org/html/rfc3501 IMAP4rev1 , and does its best to get along with servers that have buggy, unreliable, or incomplete IMAP implementations. .PP Larch has been tested on and is known to work well with the following IMAP servers: .IP \(bu .B Dovecot .IP \(bu .B Gmail .IP \(bu .B Microsoft Exchange 2003 .PP The following servers are known to work, but with caveats: .IP \(bu .B Yahoo! Mail .PP The following servers do not work well with Larch: .IP \(bu .B BlitzMail Buggy server implementation; fails to properly quote or escape some IMAP responses, which can cause Net::IMAP to hang waiting for a terminating character that will never arrive. .PP .SS Gmail quirks Gmail's IMAP implementation is quirky. Larch does its best to work around these quirks whenever possible, but here are a few things to watch out for: .PP .BR "Some messages could not be FETCHed " error .PP This error indicates that a message on Gmail is corrupt, and Gmail itself is unable to read it. The message will continue to show up in the mailbox, but all attempts to access it via IMAP, POP, or the Gmail web interface will result in errors. Larch will try to skip these messages and continue processing others if possible. .PP It's not clear how this corruption occurs or exactly what kind of corruption causes these errors, although in every case I'm aware of, the corrupt message has originated outside of Gmail (Gmail itself does not corrupt the message). There is currently no known solution for this problem apart from deleting the corrupted messages. .PP .B Folder names cannot contain leading or trailing whitespace .PP Most IMAP servers allow folder names to contain leading and trailing whitespace, such as " folder ". Gmail does not. When copying folders to Gmail, Larch will automatically remove leading and trailing whitespace in folder names to prevent errors. .SS Yahoo! mail quirks Yahoo! doesn't officially support IMAP access for general usage, but Larch is able to connect to imap.mail.yahoo.com and imap-ssl.mail.yahoo.com by using a fairly well-known trick. That said, as with anything tricky, there are caveats. .PP .B No hierarchical folders .PP Similar to Gmail, Yahoo! Mail doesn't allow hierarchical (nested) folders. If you try to copy a folder hierarchy to Yahoo!, it will work, but you'll end up with a set of folders named "folder" and "folder.subfolder" rather than seeing "subfolder" as an actual subfolder of "folder". .PP .B No custom flags .PP Yahoo! Mail IMAP doesn't support custom message flags, such as the tags and junk/not junk flags used by Thunderbird. When transferring messages with custom flags to a Yahoo! Mail IMAP account, the custom flags will be lost. .PP .B Here there be dragons .PP Larch's support for Yahoo! Mail is very new and very lightly tested. Given its newness and the fact that Yahoo!'s IMAP gateway isn't official, there are likely to be other quirks we're not yet aware of. There's also no guarantee that Yahoo! won't shut down its IMAP gateway, deprecate the trick Larch uses to connect, or just outright block Larch. Use at your own risk. .SH BUGS 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. .PP Net::IMAP in Ruby 1.8 has also been known to hang when it can't parse a server response, either because the response itself is malformed or because of a bug in Net::IMAP's parser. This is rare, but it happens. Unfortunately there's nothing Larch can do about this. .SH EXAMPLE .B Larch is run from the command line. The following examples demonstrate how to run \fBLarch\fR using only command line arguments, but you may also place these options in a config file and run \fBLarch\fR without any arguments if you prefer. .PP At a minimum, you must \fIspecify a source server and a destination server\fR in the form of IMAP URIs: .PP .nf .RS larch \-\-from imap://mail.example.com \\ \-\-to imap://imap.gmail.com .RE .fi .PP \fBLarch\fR will prompt you for the necessary usernames and passwords, then sync the contents of the source's INBOX folder to the destination's INBOX folder. .PP To \fIconnect using SSL\fR, specify a URI beginning with \fBimaps://\fR: .PP .nf .RS larch \-\-from imaps://mail.example.com \\ \-\-to imaps://imap.gmail.com .RE .fi .PP If you'd like to \fIsync a specific folder\fR other than INBOX, specify the source and destination folders using \fB\-\-from\-folder\fR and \fB\-\-to\-folder\fR. Folder names containing spaces must be enclosed in quotes: .PP .nf .RS larch \-\-from imaps://mail.example.com \\ \-\-to imaps://imap.gmail.com \\ \-\-from\-folder \(aqSent Mail\(aq \-\-to\-folder \(aqSent Mail\(aq .RE .fi .PP To \fIsync all folders\fR, use the \fB\-\-all\fR option (or \fB\-\-all\-subscribed\fR if you only want to \fIsync subscribed folders\fR): .PP .nf .RS larch \-\-from imaps://mail.example.com \\ \-\-to imaps://imap.gmail.com \-\-all .RE .fi .PP By default \fBLarch\fR will create folders on the destination server if they don't already exist. To prevent this, add the \fB\-\-no\-create\-folder\fR option: .PP .nf .RS larch \-\-from imaps://mail.example.com \\ \-\-to imaps://imap.gmail.com \-\-all \\ \-\-no\-create\-folder .RE .fi .PP You can \fIprevent Larch from syncing one or more folders\fR by using the \fB\-\-exclude\fR option, which accepts multiple arguments: .PP .nf .RS larch \-\-from imaps://mail.example.com \\ \-\-to imaps://imap.gmail.com \-\-all \\ \-\-exclude Spam Trash Drafts "[Gmail]/*" .RE .fi .PP If your exclusion list is long or complex, create a text file with one exclusion pattern per line and tell \fBLarch\fR to load it with the \fB\-\-exclude\-file\fR option: .PP .nf .RS larch \-\-from imaps://mail.example.com \\ \-\-to imaps://imap.gmail.com \-\-all \\ \-\-exclude\-file exclude.txt .RE .fi .PP The wildcard characters \fB*\fR and \fB?\fR are supported in exclusion lists. You may also use a regular expression by enclosing a pattern in forward slashes, so the previous example could be achieved with the pattern \fB/(Spam|Trash|Drafts|\\[Gmail\]\\/.*)/\fR .SH AUTHORS Adapted from the program's documentation for Debian by Martín Ferrari .