[DRE-commits] [larch] 01/01: Make package suitable for first upload.
Martín Ferrari
tincho at moszumanska.debian.org
Tue Mar 25 18:53:34 UTC 2014
This is an automated email from the git hooks/post-receive script.
tincho pushed a commit to branch master
in repository larch.
commit 96443acba41bf4e11de25ff4f11f2c9b84491cd4
Author: Martín Ferrari <tincho at debian.org>
Date: Tue Mar 25 18:53:15 2014 +0000
Make package suitable for first upload.
---
debian/larch.1 | 386 +++++++++++++++++++++++++++++++++++++++++++++++++
debian/larch.docs | 1 +
debian/larch.manpages | 1 +
debian/ruby-larch.docs | 2 -
4 files changed, 388 insertions(+), 2 deletions(-)
diff --git a/debian/larch.1 b/debian/larch.1
new file mode 100644
index 0000000..cb376c7
--- /dev/null
+++ b/debian/larch.1
@@ -0,0 +1,386 @@
+.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
+<tincho at tincho.org>.
diff --git a/debian/larch.docs b/debian/larch.docs
new file mode 100644
index 0000000..e475c53
--- /dev/null
+++ b/debian/larch.docs
@@ -0,0 +1 @@
+README.rdoc
diff --git a/debian/larch.manpages b/debian/larch.manpages
new file mode 100644
index 0000000..cb8d06e
--- /dev/null
+++ b/debian/larch.manpages
@@ -0,0 +1 @@
+debian/larch.1
diff --git a/debian/ruby-larch.docs b/debian/ruby-larch.docs
deleted file mode 100644
index 0d5eab8..0000000
--- a/debian/ruby-larch.docs
+++ /dev/null
@@ -1,2 +0,0 @@
-# FIXME: READMEs found
-# README.rdoc
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-ruby-extras/larch.git
More information about the Pkg-ruby-extras-commits
mailing list