{"id":13880516,"url":"https://github.com/rgrove/larch","last_synced_at":"2025-07-16T17:30:33.153Z","repository":{"id":517941,"uuid":"146065","full_name":"rgrove/larch","owner":"rgrove","description":":skull: Larch copies messages from one IMAP server to another. No longer maintained.","archived":true,"fork":false,"pushed_at":"2016-07-24T15:47:38.000Z","size":469,"stargazers_count":616,"open_issues_count":30,"forks_count":66,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-07-07T02:06:29.026Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rgrove.png","metadata":{"files":{"readme":"README.rdoc","changelog":"HISTORY","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-03-08T22:37:35.000Z","updated_at":"2025-05-10T15:20:23.000Z","dependencies_parsed_at":"2022-07-18T05:21:41.965Z","dependency_job_id":null,"html_url":"https://github.com/rgrove/larch","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/rgrove/larch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgrove%2Flarch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgrove%2Flarch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgrove%2Flarch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgrove%2Flarch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rgrove","download_url":"https://codeload.github.com/rgrove/larch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgrove%2Flarch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527541,"owners_count":23782480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:03:06.238Z","updated_at":"2025-07-16T17:30:32.860Z","avatar_url":"https://github.com/rgrove.png","language":"Ruby","readme":"= Larch\n\n*Note:* I no longer actively develop or use Larch, so it is effectively\nunmaintained. Many people claim it still works well for them, so feel free\nto use it, but please don't expect support, bug fixes, or new features.\n\nLarch is a tool to copy messages from one IMAP server to another quickly and\nsafely. It's smart enough not to copy messages that already exist on the\ndestination and robust enough to deal with interruptions caused by flaky\nconnections or misbehaving servers.\n\nLarch is particularly well-suited for copying email to, from, or between Gmail\naccounts.\n\n*Author*::    Ryan Grove (mailto:ryan@wonko.com)\n*Version*::   1.1.2 (2013-01-24)\n*Copyright*:: Copyright (c) 2013 Ryan Grove. All rights reserved.\n*License*::   GPL 2.0 (http://opensource.org/licenses/gpl-2.0.php)\n*Website*::   http://github.com/rgrove/larch\n\n== Installation\n\nLatest stable release:\n\n  gem install larch\n\nLatest development version:\n\n  gem install larch --pre\n\n== Usage\n\n  larch [config section] [options]\n  larch --from \u003curi\u003e --to \u003curi\u003e [options]\n\n  Server Options:\n           --from, -f \u003cs\u003e:   URI of the source IMAP server\n    --from-folder, -F \u003cs\u003e:   Source folder to copy from (default: INBOX)\n      --from-pass, -p \u003cs\u003e:   Source server password (default: prompt)\n      --from-user, -u \u003cs\u003e:   Source server username (default: prompt)\n             --to, -t \u003cs\u003e:   URI of the destination IMAP server\n      --to-folder, -T \u003cs\u003e:   Destination folder to copy to (default: INBOX)\n        --to-pass, -P \u003cs\u003e:   Destination server password (default: prompt)\n        --to-user, -U \u003cs\u003e:   Destination server username (default: prompt)\n\n  Copy Options:\n                --all, -a:   Copy all folders recursively\n     --all-subscribed, -s:   Copy all subscribed folders recursively\n             --delete, -d:   Delete messages from the source after copying\n                             them, or if they already exist at the destination\n           --exclude \u003cs+\u003e:   List of mailbox names/patterns that shouldn't be\n                             copied\n       --exclude-file \u003cs\u003e:   Filename containing mailbox names/patterns that\n                             shouldn't be copied\n            --expunge, -x:   Expunge deleted messages from the source\n         --sync-flags, -S:   Sync message flags from the source to the\n                             destination for messages that already exist at the\n                             destination\n\n  General Options:\n         --config, -c \u003cs\u003e:   Specify a non-default config file to use (default:\n                             ~/.larch/config.yaml)\n           --database \u003cs\u003e:   Specify a non-default message database to use\n                             (default: ~/.larch/larch.db)\n            --dry-run, -n:   Don't actually make any changes\n        --max-retries \u003ci\u003e:   Maximum number of times to retry after a\n                             recoverable error (default: 3)\n       --no-create-folder:   Don't create destination folders that don't\n                             already exist\n          --ssl-certs \u003cs\u003e:   Path to a trusted certificate bundle to use to\n                             verify server SSL certificates\n             --ssl-verify:   Verify server SSL certificates\n      --verbosity, -V \u003cs\u003e:   Output verbosity: debug, info, warn, error, or\n                             fatal (default: info)\n            --version, -v:   Print version and exit\n               --help, -h:   Show this message\n\n== Usage Examples\n\nLarch is run from the command line. The following examples demonstrate how to\nrun Larch using only command line arguments, but you may also place these\noptions in a config file and run Larch without any arguments if you prefer. See\nthe \"Configuration\" section below for more details.\n\nFor an overview of all available options, run:\n\n  larch -h\n\nAt a minimum, you must \u003cb\u003especify a source server and a destination server\u003c/b\u003e\nin the form of IMAP URIs:\n\n  larch --from imap://mail.example.com --to imap://imap.gmail.com\n\nLarch will prompt you for the necessary usernames and passwords, then sync the\ncontents of the source's +INBOX+ folder to the destination's INBOX folder.\n\nTo \u003cb\u003econnect using SSL\u003c/b\u003e, specify a URI beginning with \u003ctt\u003eimaps://\u003c/tt\u003e:\n\n  larch --from imaps://mail.example.com --to imaps://imap.gmail.com\n\nIf you'd like to \u003cb\u003esync a specific folder\u003c/b\u003e other than +INBOX+, specify the\nsource and destination folders using \u003ctt\u003e--from-folder\u003c/tt\u003e and\n\u003ctt\u003e--to-folder\u003c/tt\u003e. Folder names containing spaces must be enclosed in quotes:\n\n  larch --from imaps://mail.example.com --to imaps://imap.gmail.com \\\n    --from-folder 'Sent Mail' --to-folder 'Sent Mail'\n\nTo \u003cb\u003esync all folders\u003c/b\u003e, use the \u003ctt\u003e--all\u003c/tt\u003e option (or\n\u003ctt\u003e--all-subscribed\u003c/tt\u003e if you only want to \u003cb\u003esync subscribed folders\u003c/b\u003e):\n\n  larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all\n\nBy default Larch will create folders on the destination server if they don't\nalready exist. To prevent this, add the \u003ctt\u003e--no-create-folder\u003c/tt\u003e option:\n\n  larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \\\n    --no-create-folder\n\nYou can \u003cb\u003eprevent Larch from syncing one or more folders\u003c/b\u003e by using the\n\u003ctt\u003e--exclude\u003c/tt\u003e option, which accepts multiple arguments:\n\n  larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \\\n    --exclude Spam Trash Drafts \"[Gmail]/*\"\n\nIf your exclusion list is long or complex, create a text file with one exclusion\npattern per line and tell Larch to load it with the \u003ctt\u003e--exclude-file\u003c/tt\u003e\noption:\n\n  larch --from imaps://mail.example.com --to imaps://imap.gmail.com --all \\\n    --exclude-file exclude.txt\n\nThe wildcard characters \u003ctt\u003e*\u003c/tt\u003e and \u003ctt\u003e?\u003c/tt\u003e are supported in exclusion\nlists. You may also use a regular expression by enclosing a pattern in\nforward slashes, so the previous example could be achieved with the\npattern \u003ctt\u003e/(Spam|Trash|Drafts|\\[Gmail\\]\\/.*)/\u003c/tt\u003e\n\n== Configuration\n\nWhile it's possible to control Larch entirely from the command line, this can be\ninconvenient if you need to specify a lot of options or if you run Larch\nfrequently and can't always remember which options to use. Using a configuration\nfile can simplify things.\n\nBy default, Larch looks for a config file at \u003ctt\u003e~/.larch/config.yaml\u003c/tt\u003e and\nuses it if found. You may specify a custom config file using the\n\u003ctt\u003e--config\u003c/tt\u003e command line option.\n\nThe Larch configuration file is a simple YAML[http://yaml.org/] file that may\ncontain multiple sections, each with a different set of options, as well as a\nspecial +default+ section. The options in the +default+ section will be used\nunless they're overridden either in another config section or on the command\nline.\n\n=== Example\n\nHere's a sample Larch config file:\n\n  default:\n    all-subscribed: true # Copy all subscribed folders by default\n\n  # Copy mail from Gmail to my server, excluding stuff I don't want.\n  gmail to my server:\n    from: imaps://imap.gmail.com\n    from-user: example\n    from-pass: secret\n\n    to: imaps://mail.example.com\n    to-user: example\n    to-pass: secret\n\n    exclude:\n      - \"[Gmail]/Sent Mail\"\n      - \"[Gmail]/Spam\"\n      - \"[Gmail]/Trash\"\n\n  # Copy mail from my INBOX to Gmail's INBOX\n  my inbox to gmail inbox:\n    all-subscribed: false\n\n    from: imaps://mail.example.com\n    from-folder: INBOX\n    from-user: example\n    from-pass: secret\n\n    to: imaps://imap.gmail.com\n    to-folder: INBOX\n    to-user: example\n    to-pass: secret\n\nThis file contains three sections. The options from +default+ will be used in\nall other sections as well unless they're overridden.\n\nTo specify which config section you want Larch to use, just pass its name on the\ncommand line (use quotes if the name contains spaces):\n\n  larch 'gmail to my server'\n\nIf you specify additional command line options, they'll override options in the\nconfig file:\n\n  larch 'gmail to my server' --from-user anotheruser\n\nRunning Larch with no command line arguments will cause the +default+ section\nto be used. With the example above, this will result in an error since the\n+default+ section doesn't contain the required +from+ and +to+ options, but if\nyou only need to use Larch with a single configuration, you could use the\n+default+ section for everything and save yourself some typing on the command\nline.\n\n== Server Compatibility\n\nLarch should work well with any server that properly supports\nIMAP4rev1[http://tools.ietf.org/html/rfc3501], and does its best to get along\nwith servers that have buggy, unreliable, or incomplete IMAP implementations.\n\nLarch has been tested on and is known to work well with the following IMAP\nservers:\n\n* Dovecot\n* Gmail\n* Microsoft Exchange 2003\n\nThe following servers are known to work, but with caveats:\n\n* Yahoo! Mail\n\nThe following servers do not work well with Larch:\n\n* BlitzMail - Buggy server implementation; fails to properly quote or escape\n  some IMAP responses, which can cause Net::IMAP to hang waiting for a\n  terminating character that will never arrive.\n\n=== Gmail Quirks\n\nGmail's IMAP implementation is quirky. Larch does its best to work around these\nquirks whenever possible, but here are a few things to watch out for:\n\n==== \"Some messages could not be FETCHed\" error\n\nThis error indicates that a message on Gmail is corrupt, and Gmail itself is\nunable to read it. The message will continue to show up in the mailbox, but all\nattempts to access it via IMAP, POP, or the Gmail web interface will result in\nerrors. Larch will try to skip these messages and continue processing others\nif possible.\n\nIt's not clear how this corruption occurs or exactly what kind of corruption\ncauses these errors, although in every case I'm aware of, the corrupt message\nhas originated outside of Gmail (Gmail itself does not corrupt the message).\nThere is currently no known solution for this problem apart from deleting the\ncorrupted messages.\n\n==== Folder names cannot contain leading or trailing whitespace\n\nMost IMAP servers allow folder names to contain leading and trailing whitespace,\nsuch as \"  folder  \". Gmail does not. When copying folders to Gmail, Larch will\nautomatically remove leading and trailing whitespace in folder names to prevent\nerrors.\n\n=== Yahoo! Mail Quirks\n\nYahoo! doesn't officially support IMAP access for general usage, but Larch is\nable to connect to imap.mail.yahoo.com and imap-ssl.mail.yahoo.com by using a\nfairly well-known trick. That said, as with anything tricky, there are caveats.\n\n==== No hierarchical folders\n\nSimilar to Gmail, Yahoo! Mail doesn't allow hierarchical (nested) folders. If\nyou try to copy a folder hierarchy to Yahoo!, it will work, but you'll end up\nwith a set of folders named \"folder\" and \"folder.subfolder\" rather than seeing\n\"subfolder\" as an actual subfolder of \"folder\".\n\n==== No custom flags\n\nYahoo! Mail IMAP doesn't support custom message flags, such as the tags and\njunk/not junk flags used by Thunderbird. When transferring messages with custom\nflags to a Yahoo! Mail IMAP account, the custom flags will be lost.\n\n==== Here there be dragons\n\nLarch's support for Yahoo! Mail is very new and very lightly tested. Given its\nnewness and the fact that Yahoo!'s IMAP gateway isn't official, there are likely\nto be other quirks we're not yet aware of. There's also no guarantee that Yahoo!\nwon't shut down its IMAP gateway, deprecate the trick Larch uses to connect, or\njust outright block Larch. Use at your own risk.\n\n== Known Issues\n\n* Larch uses Ruby's Net::IMAP standard library for all IMAP operations. While\n  Net::IMAP is generally a very solid library, it contains a bug that can\n  cause a deadlock to occur if a connection drops unexpectedly (either due to\n  network issues or because the server closed the connection without warning)\n  when the server has already begun sending a response and Net::IMAP is\n  waiting to receive more data. If this happens, Net::IMAP will continue waiting\n  forever without passing control back to Larch, and you will need to manually\n  kill and restart Larch.\n\n  Net::IMAP in Ruby 1.8 has also been known to hang when it can't parse a server\n  response, either because the response itself is malformed or because of a\n  bug in Net::IMAP's parser. This is rare, but it happens. Unfortunately there's\n  nothing Larch can do about this.\n\n* The Ruby package on Debian, Ubuntu, and some other Debian-based Linux\n  distributions doesn't include the OpenSSL standard library. If you see an\n  error like \u003ctt\u003euninitialized constant Larch::IMAP::OpenSSL (NameError)\u003c/tt\u003e\n  when running Larch, you may need to install the \u003ctt\u003elibopenssl-ruby\u003c/tt\u003e\n  package. Please feel free to complain to the maintainer of your distribution's\n  Ruby packages.\n\n== Support\n\nThe Larch mailing list is the best place for questions, comments, and discussion\nabout Larch. You can join the list or view the archives at\nhttp://groups.google.com/group/larch\n\nFirst-time senders to the list are moderated to prevent spam, so there may be a\ndelay before your first message shows up.\n\n== Contributors\n\nLarch was created and is maintained by Ryan Grove \u003cryan@wonko.com\u003e.\n\nThe following lovely people have also contributed to Larch:\n\n* Torey Heinz \u003ctorey@ihswebdesign.com\u003e\n* Edgardo Hames \u003cehames@gmail.com\u003e\n* Andrew Hobson \u003cahobson@damballa.com\u003e\n* Justin Mazzi \u003chh@mailheist.com\u003e\n\n== Credit\n\nThe Larch::IMAP class borrows heavily from Sup[http://sup.rubyforge.org] by\nWilliam Morgan, the source code of which should be required reading if you're\ndoing anything with IMAP in Ruby.\n\nLarch uses the excellent Trollop[http://trollop.rubyforge.org] command-line\noption parser (also by William Morgan) and the\nHighLine[http://highline.rubyforge.org] command-line IO library (by James Edward\nGray II).\n\n== License\n\nCopyright (c) 2013 Ryan Grove \u003cryan@wonko.com\u003e\n\nLicensed under the GNU General Public License version 2.0.\n\nThis program is free software; you can redistribute it and/or modify it under\nthe terms of version 2.0 of the GNU General Public License as published by the\nFree Software Foundation.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE.  See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with\nthis program; if not, visit http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt\nor write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,\nBoston, MA 02111-1307 USA.\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgrove%2Flarch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frgrove%2Flarch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgrove%2Flarch/lists"}