Provided by: larch_1.1.2-2_all bug

NAME

       larch - copy messages from one IMAP server to another

SYNOPSIS

       larch [options]

       larch [--from URI] [--to URI]

DESCRIPTION

       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.

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

OPTIONS

   Server options
       --from, -f URI
              URI of the source IMAP server.

       --from-folder, -F FOLDER
              Source folder to copy from. Default is INBOX.

       --from-pass, -p PASSWD
              Source server password. Default is to prompt the user.

       --from-user, -u USER
              Source server username. Default is to prompt the user.

       --to, -t URI
              URI of the destination IMAP server.

       --to-folder, -T FOLDER
              Destination folder to copy to. Default is INBOX.

       --to-pass, -P PASSWD
              Destination server password. Default is to prompt the user.

       --to-user, -U USER
              Destination server username. Default is to prompt the user.

   Copy options
       --all, -a
              Copy all folders recursively.

       --all-subscribed, -s
              Copy all subscribed folders recursively.

       --delete, -d
              Delete messages from the source after copying them, or if they already exist at the
              destination.

       --exclude PATTERN [ PATTERN... ]
              List of mailbox names/patterns that shouldn't be copied.

       --exclude-file FILE
              Filename containing mailbox names/patterns that shouldn't be copied.

       --expunge, -x
              Expunge deleted messages from the source.

       --sync-flags, -S
              Sync message flags from the source to the destination  for  messages  that  already
              exist at the destination.

   General options
       --config, -c FILE
              Specify a non-default config file to use. Default is ~/.larch/config.yaml.

       --database FILE
              Specify a non-default message database to use. Default is ~/.larch/larch.db.

       --dry-run, -n
              Don't actually make any changes.

       --max-retries NUM
              Maximum number of times to retry after a recoverable error. Default is 3.

       --no-create-folder
              Don't create destination folders that don't already exist.

       --ssl-certs FILE
              Path to a trusted certificate bundle to use to verify server SSL certificates.

       --ssl-verify
              Verify server SSL certificates.

       --verbosity, -V STR
              Output verbosity: debug, info, warn, error, or fatal. Default is info.

       --version, -v
              Print version and exit.

       --help, -h
              Show a help message.

CONFIGURATION

       While  it's  possible  to  control  Larch  entirely  from  the  command  line, this can be
       inconvenient if you need to specify a lot of options or if you run  Larch  frequently  and
       can't  always  remember  which  options  to  use.  Using a configuration file can simplify
       things.

       By default, Larch looks for a config file at ~/.larch/config.yaml and uses  it  if  found.
       You may specify a custom config file using the --config command line option.

       The  Larch  configuration  file  is a simple YAML ⟨http://yaml.org/⟩ file that may contain
       multiple sections, each with a different set of options, as  well  as  a  special  default
       section.  The options in the default section will be used unless they're overridden either
       in another config section or on the command line.

       Here's a sample Larch config file:

              # 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

       This file contains three sections.  The options from default will be  used  in  all  other
       sections as well unless they're overridden.

       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):

              larch 'gmail to my server'

       If you specify additional command line options, they'll override  options  in  the  config
       file:

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

       Running  Larch  with  no command line arguments will cause the default section to be used.
       With the example above, this will result in an error since  the  default  section  doesn't
       contain  the required from and to options, but if you only need to use Larch with a single
       configuration, you could use the default section for everything  and  save  yourself  some
       typing on the command line.

FILES

       ~/.larch/config.yaml

NOTES

   Server compatibility
       Larch should work well with any server that properly supports IMAP4rev1 ⟨http://
       tools.ietf.org/html/rfc3501⟩ , 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:

       •      DovecotGmailMicrosoft Exchange 2003

       The following servers are known to work, but with caveats:

       •      Yahoo! Mail

       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 Net::IMAP to hang waiting for  a  terminating  character
              that will never arrive.

   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:

       Some messages could not be FETCHed error

       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.

       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.

       Folder names cannot contain leading or trailing whitespace

       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.

   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.

       No hierarchical folders

       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".

       No custom flags

       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.

       Here there be dragons

       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.

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.

       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.

EXAMPLE

       Larch  is  run from the command line.  The following examples demonstrate how to run Larch
       using only command line arguments, but you may also place these options in a  config  file
       and run Larch without any arguments if you prefer.

       At  a  minimum,  you  must specify a source server and a destination server in the form of
       IMAP URIs:

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

       Larch 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.

       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.  Folder names  containing  spaces
       must be enclosed in quotes:

              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,
       which accepts multiple arguments:

              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 may 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]\/.*)/

AUTHORS

       Adapted from the program's documentation for Debian by Martín Ferrari <tincho@tincho.org>.

                                                                                         LARCH(1)