mboxgrep/doc/mboxgrep.texi

282 lines
6.6 KiB
Plaintext

\input texinfo
@setfilename mboxgrep.info
@settitle Grep through mailboxes
@finalout
@setchapternewpage odd
@set EDITION 0.7
@set VERSION 0.7.12a
@set UPDATED 21 May 2023
@dircategory Mail
@direntry
* mboxgrep: (mboxgrep). A mail folder scanning utility.
@end direntry
@node Top, , , (dir)
@ifinfo
This file documents @code{mboxgrep} (version @value{VERSION}), a
mailbox scanning utility.
Copyright (C) 2000, 2001, 2002, 2003 Daniel Spiljar
@end ifinfo
@menu
* Introduction:: A short preface.
* Invoking:: Command-line arguments.
* Examples:: A few examples of usage.
* Bugs:: What to do with bugs and similar vermin.
* To Vicky:: Author's dedication.
@end menu
@node Introduction, Invoking, , Top
@chapter Introduction
@cindex introduction
@cindex preface
@code{mboxgrep} is a small, non-interactive utility that scans mail folders
for messages matching regular expressions.
It supports basic and extended POSIX regular expressions. @code{Perl}-style
regular expressions are supported as well, if @code{mboxgrep} is linked with
PCRE library.
Found messages can be either displayed on standard output, counted, deleted,
piped to a specified command, or copied to another mailbox.
It can read and write a variety of folder formats:
@itemize @bullet
@item
mbox folders, either plain or compressed
@item
MH folders
@item nnml and nnmh folders used by Gnus
@item @code{qmail}-style maildirs
@end itemize
Additionally, it can read mbox folders or output from another @code{mboxgrep}
process from standard input. It does so if a single dash (-) is given
as a file name.
@node Invoking, Examples, Introduction, Top
@chapter Command-Line Arguments
@cindex arguments
The syntax of @code{mboxgrep} invocation is:
@example
mboxgrep [OPTIONS] PATTERN [MAILBOX]
@end example
@menu
* Miscellaneous::
* File locking::
* Regexp selection::
* Output control::
* Search scope selection::
* Mailbox type selection::
@end menu
@node Miscellaneous, File locking, , Invoking
@table @samp
@item --help
@itemx -h
Display a brief help screen and exit.
@item --version
@itemx -V
Display program version and copyright information and exit.
@item --recursive
@itemx -r
Descend into directories recursively.
@end table
@node File locking, Regexp selection, Miscellaneous, Invoking
When accessing mbox folders, @code{mboxgrep} puts a shared lock on
files by default. Note that mbox folders normally should not be accessed
without locking.
@table @samp
@item --file-lock=METHOD
@itemx -l METHOD
Specify file locking METHOD. @code{mboxgrep} supports @code{flock} and
@code{fcntl} file locking. However, one of these methods may be
unimplemented on your operating system and thus not available in
@code{mboxgrep} at run time. To disable file locking, specify @code{none}.
@item --no-file-lock
@itemx -nl
Do not attempt to lock mbox folder files.
@end table
@node Regexp selection, Output control, File locking, Invoking
@table @samp
@item --extended-regexp
@itemx -E
PATTERN is an extended regular expression.
@item --basic-regexp
@itemx -G
PATTERN is a basic regular expression.
@item --perl-regexp
@itemx -P
PATTERN is a Perl regular expression.
@item --regexp=PATTERN
@itemx -e PATTERN
Use PATTERN as a regular expression.
@item --ignore-case
@itemx -i
Perform case-insensitive search.
@item --invert-match
@itemx -v
Invert the sense of matching, i.e. select only non-matching messages.
@end table
@node Output control, Search scope selection, Regexp selection, Invoking
By default, @code{mboxgrep} writes found messages to standard output.
The options below change such behavior.
@table @samp
@item --count
@itemx -c
Suppress normal output and print the count of matching (or non-matching,
if used with the @code{-v} option) messages.
@item --delete
@itemx -d
Suppress normal output and delete selected messages.
Use with extreme caution.
@item --no-duplicates
@itemx -nd
Ignore duplicate messages.
@item --output=FOLDER
@itemx -o FOLDER
Suppress normal output and write messages to destination folder FOLDER
instead.
Note that @code{mboxgrep} assumes the output folder is of the same format
as the input folder. Currently there is no possibility to convert folders.
@item --pipe=COMMAND
@itemx -p COMMAND
Suppress normal output and pipe each selected message to a separate
instance of COMMAND.
@item --no-messages
@itemx -s
Suppress error messages.
@item --debug
Print messages useful for debugging.
@end table
@node Search scope selection, Mailbox type selection, Output control, Invoking
@table @samp
@item --headers
@itemx -H
Match PATTERN against message headers.
@item --body
@itemx -B
Match PATTERN against message body.
@end table
@node Mailbox type selection, , Search scope selection, Invoking
@table @samp
@item --mailbox-format=FORMAT
@itemx -m FORMAT
Specify mailbox FORMAT. Supported formats are @code{mbox} (default),
@code{zmbox} (gzip compressed mbox), @code{bz2mbox} (bzip2 compressed
mbox) @code{mh}, @code{nnml}, @code{nnmh}, and @code{maildir}.
@end table
@node Examples, Bugs, Invoking, Top
@chapter Examples
@cindex example
Scan @env{$MAIL} for messages from Dirty Harry:
@example
mboxgrep -H '^From:.*callahan@@sanfranciscopolice\.org' $MAIL
@end example
Re-mail to George messages that mention his name:
@example
mboxgrep --pipe="/usr/lib/sendmail george" --ignore-case george ~/Mail/*
@end example
Display all messages in folder @file{~/Mail/incoming}, except those that
appear to originate from AOL:
@example
mboxgrep -v -H '^Received:.*aol\.com' ~/Mail/incoming
@end example
Do a case-insensitive scan of @file{~/Mail/incoming} for messages with subject
``Weekly News'' and write them to folder @file{~/Mail/archive}:
@example
mboxgrep -o ~/Mail/archive -H -i '^Subject: Weekly News' ~/Mail/incoming
@end example
Count @emph{all} messages stored in folder @file{spam}, ignoring duplicates:
@example
mboxgrep -nd -c . spam
@end example
@node Bugs, To Vicky, Examples, Top
@chapter Detecting Vermin
@cindex bug, insect, vermin, bugreport
Shortly, if @code{mboxgrep} crashes and/or works differently than described
in this manual, you have found a bug.
Please report bugs to @email{dspiljar@@datatipp.se}.
Instructions how to reproduce the bug or output from a debugger would be
highly appreciated. Please do not, however, send any core dumps.
@node To Vicky, , Bugs, Top
@chapter Author's Dedication
@cindex vicky, cat, memory, love
@code{Mboxgrep} is dedicated in loving memory of Vicky, my cat who died
of tumor on Sep 12, 2002.
You haven't been long with us, but you gave us a lot of joy and all
your big heart that stopped ticking too early. I will never forget
you. Sleep well, little friend.
@bye @c cruel world