X-Git-Url: https://fleuret.org/cgi-bin/gitweb/gitweb.cgi?p=mymail.git;a=blobdiff_plain;f=mymail.1;h=09fa3248f2d4a42e33e6aec5b6f597a9466cae72;hp=79eff223c266de05e2fb544a438908d42edbb772;hb=HEAD;hpb=a6658570670b49312a48d2fc5f1a80526e3c74a2 diff --git a/mymail.1 b/mymail.1 index 79eff22..09fa324 100644 --- a/mymail.1 +++ b/mymail.1 @@ -1,4 +1,4 @@ -.TH "MYMAIL" "0.9" "February 2013" "Francois Fleuret" "User Commands" +.TH "MYMAIL" "0.9.10" "July 2014" "Francois Fleuret" "User Commands" \" This man page was written by Francois Fleuret \" and is distributed under a Creative Commons Attribution-Share Alike @@ -10,57 +10,187 @@ mymail \- A simple command line utility for indexing and searching mbox files .SH "SYNOPSIS" -\fBmymail\fP [\fIoptions\fR] [\fI\fR [\fI\fR ...]] +\fBmymail\fP [\fIoptions\fR] [\fI\fR [\fI\fR ... ]|\fI\fR [\fI\fR ... ]] .SH "DESCRIPTION" -\fBmymail\fP is a command line utility for to index mbox files and -perform quick searches based on sender, subject, etc. +\fBmymail\fP is a command line utility to index mbox files, search for +mails based on sender, subject, etc. and generate result mbox files. -It is similar in spirit to other existing software such as mu or -notmuch. +It is similar in spirit to other tools such as mu or notmuch, but is +overall simpler. -.SH "SEARCH SYNTAX" +.SH "OPTIONS" +.TP +\fB-h\fR, \fB--help\fR +display help and exit +.TP +\fB-v\fR, \fB--version\fR +print the version number +.TP +\fB-q\fR, \fB--quiet\fR +do not write information during the search +.TP +\fB-t\fR, \fB--use-leading-time\fR +use the time stamp from the leading line of each mail and not the +Date: field +.TP +\fB-f\fR, \fB--do-not-discard-mails-from-the-future\fR +keep mails with a date (more than 24h) in the future, which are +discarded by default +.TP +\fB-p \fR, \fB--db-pattern \fR +set the db filename pattern for recursive search +.TP +\fB-r \fR, \fB--db-root \fR +set the db root path for recursive search +.TP +\fB-l \fR, \fB--db-list \fR +set the semicolon-separated list of db files for search +.TP +\fB-m \fR, \fB--mbox-pattern \fR +set the mbox filename pattern for recursive search +.TP +\fB-s \fR, \fB--search \fR +search for matching mails in the db file. Multiple search requests can +be combined, and only mails fulfilling all of them will be extracted. +.TP +\fB-d \fR, \fB--db-file-output \fR +set the db filename for indexing +.TP +\fB-i\fR, \fB--index\fR +index mails in the mailboxes located recursively anywhere in the +directories following the options on the command lines +.TP +\fB-o \fR, \fB--output \fR +set the result mbox filename. If it is not set, the standard output is +used +.TP +\fB-n \fR, \fB--nb-mails-max \fR +set the maximum number of mails to extract (default is 250) +.TP +\fB-a \fR, \fB--default-search \fR +set the default search key. If a search request is not understood, +it is interpreted as the regexp with this default search key + +.SH "ENVIRONMENT VARIABLES" + +.TP +\fBMYMAIL_DB_PATTERN\fR +defaut value for the --db-pattern argument +.TP +\fBMYMAIL_DB_ROOT\fR +defaut value for the --db-root argument +.TP +\fBMYMAIL_DB_LIST\fR +defaut value for the --db-list argument +.TP +\fBMYMAIL_DB_FILE\fR +defaut value for the --db-file-output argument +.TP +\fBMYMAILRC \fR +configuration file, default is ${HOME}/.mymailrc + +.SH "SEARCH CONDITIONS" + +A search condition is either a time-related condition +('today', 'yesterday', etc.), or a single-character key, followed by a +space and a regexp, which can itself contain spaces. -The search conditions take the form of a single letter followed by a -space and a regexp, which can itself contain spaces. If the condition -is prefaced by the character "!" it is negated, and has to be false -for a mail to be selected. +If it is prefaced by the character "!", a condition is negated and has +to be false for a mail to be selected. .TP -\fBf \fR selects mails whose field From, From:, or Reply-To: matches the regexp. Since the initial "From " line contains the date, this search criterion can be used to restrict to a certain year or month. +\fBf \fR (from) +selects mails whose leading line 'From', or fields From:, Sender:, +Reply-To:, or Return-Path: matches the regexp. +.TP +\fBt \fR (to) +selects mails whose field To:, Cc:, or Bcc: matches the regexp. +.TP +\fBp \fR (participant) +selects mails that would be selected by \fBf\fR or \fBt\fR. +.TP +\fBs \fR (subject) +selects mails whose field Subject: matches the regexp. +.TP +\fBd \fR (date) +selects mails whose field Date: matches the regexp. +.TP +\fBb \fR (body) +selects mails whose body matches the regexp. Evaluating such a +condition requires to read the full mail from the original mboxes, +which can be slow. To speed things up, all the header conditions are +checked first. .TP -\fBd \fR selects mails whose field To:, Cc:, or Bcc: matches the regexp. +\fB1h\fR, \fB2h\fR, \fB4h\fR, \fB8h\fR, \fB24h\fR, \fB48h\fR, \fBweek\fR, \fB2weeks\fR, \fBmonth\fR, \fBtrimester\fR, \fBsemester\fR, and \fByear\fR +select mails received during the last +1, 2, 4, 8, 24, 48, 7 * 24 hours, 14 * 24 hours, 31 * 24 hours, 92 * +24 hours, 185 * 24 hours, and 365 * 24 hours respectively. .TP -\fBp \fR selects mails whose field From, From:, Reply-To:, To:, Cc:, or Bcc: matches the regexp. +\fBtoday\fR +selects mails received since midnight. .TP -\fBs \fR selects mails whose field Subject: matches the regexp. +\fByesterday\fR +selects mails received yesterday. +.TP +\fBmonday\fR, \fBtuesday\fR, ..., \fBsunday\fR +select mails received the most recent such day of the week. .SH "EXAMPLES" -To index all the mbox files present in the directory ~/archives/mails/2010 -(recursively) and create a data-base file /tmp/mymail/2010/mymail.db +The command + +.P +.nf +.B mymail --db-file-output /tmp/mymail/2010-2011/mymail.db \e +.B \ \ \ \ \ \ \ --index \e +.B \ \ \ \ \ \ \ ~/archives/mails/2010 ~/archives/mails/2011 + +.fi +will index all the mbox files present in the directories +~/archives/mails/2010 and ~/archives/mails/2011 (recursively) and +create an index file /tmp/mymail/2010-2011/mymail.db + +And + +.P +.nf +.B mymail --db-pattern '\.db$' --db-root /tmp/mymail \e +.B \ \ \ \ \ \ \ --output /tmp/mymail.mbox \e +.B \ \ \ \ \ \ \ --search 'p bob.something' \e +.B \ \ \ \ \ \ \ --search '!s spam' \e +.B \ \ \ \ \ \ \ --search 'month' -.RS -.EX -mymail --index --db-file /tmp/mymail/2010/mymail.db ~/archives/mails/2010 -.EE -.RE +.fi +will search in all the database files *.db located (recursively) in +/tmp/mymail, for all the mails having "bob.something" as sender or +recipient, without "spam" in the subject, received over the last 31 +days, and create an mbox file /tmp/mymail/mbox. -To search in all the data-base files mymail.db located (recursively) -in /tmp/mymail, for all the mails having bob.something as sender or -recipient, without "spam" in the subject, and creating a result mbox -file /tmp/mymail/mbox +.SH "FILES" -.RS -.EX -mymail --db-file mymail.db --db-root /tmp/mymail --search 'p bob.something' --search '!s spam' > /tmp/mymail.mbox -.EE -.RE +The configuration file is by default ${HOME}/.mymailrc and can also be +specified through the MYMAILRC environment variable. + +It allows to define aliases of search keys, such as: + +.P +.nf +.B alias tod=today .SH "BUGS" -None known, probably many. +The search in the mail bodies does not decode mimencoding mails, hence +will not catch patterns in encoded text. + +The mbox format is not clear for multipart messages, since the 'From' +may not always be quoted properly, so mymail uses a strict regexp to +recognize such lines. + +The date format for the Date: field is not standardized, and may not +be parsed properly. When that happens, the time stamp from the +leading 'From' line of the mail, which has a canonical form, is used. .SH "AUTHOR"