From cc10fbd22afe3212ae2f63ff80bbb1043ba4b518 Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Sat, 31 May 2025 08:40:53 +0300 Subject: [PATCH] man: update mu-index manpage Make it a bit more explicit what we ignore. --- man/mu-index.1.org | 53 +++++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/man/mu-index.1.org b/man/mu-index.1.org index af49eb02..57209220 100644 --- a/man/mu-index.1.org +++ b/man/mu-index.1.org @@ -12,56 +12,57 @@ mu-index - index e-mail messages stored in Maildirs * DESCRIPTION -*mu index* is the *mu* command for scanning the contents of Maildir directories and +*mu index* is the *mu* command for scanning the messages in Maildir directories and storing the results in a Xapian database. The data can then be queried using {{{man-link(mu-find,1)}}}. -Before the first time you run *mu index*, you must run *mu init* to initialize the -database. +Before you can run *mu index*, you must initialize *mu* and its database with +{{{man-link(mu-init,1)}}}. -*index* understands Maildirs as defined by Daniel Bernstein for +*mu index* understands Maildirs as defined by Daniel Bernstein for {{{man-link(qmail,7)}}}. In addition, it understands recursive Maildirs (Maildirs within Maildirs), Maildir++. It also supports VFAT-based Maildirs -which use *!* or *;* as the separators instead of *:*. +which use "*!"* or "*;"* as the separators, instead of the standard "*:"*. -E-mail messages which are not stored in something resembling a maildir -leaf-directory (_cur_ and _new_) are ignored, as are the cache directories for -_notmuch_ and _gnus_, and any dot-directory. +E-mail messages are only considered for indexing if they reside in a directory +named either ~cur~ or ~new~. The special (as per the Maildir-specification) +directory ~tmp~ is ignored, as are some cache directories for some other +mail-clients. Other directories are scanned recursively. -Symlinks are followed, and the directories can be spread over multiple -filesystems; however note that moving files around is much faster when multiple -filesystems are not involved. Be careful to avoid self-referential symlinks! +Symbolic links are followed, and the directories can be spread over multiple +filesystems; however, note that moving files around is much faster when they all +reside on a single file-system. Be careful to avoid self-referential symlinks! -If there is a file called _.noindex_ in a directory, the contents of that +If there is a file called ~.noindex~ in a directory, the contents of that directory and all of its subdirectories will be ignored. This can be useful to exclude certain directories from the indexing process, for example directories with spam-messages. -If there is a file called _.noupdate_ in a directory, the contents of that +If there is a file called ~.noupdate~ in a directory, the contents of that directory and all of its subdirectories will be ignored. This can be useful to speed up things you have some maildirs that never change. -_.noupdate_ does not affect already-indexed messages: you can still search for -them. _.noupdate_ is ignored when you start indexing with an empty database (such +~.noupdate~ does not affect already-indexed messages: you can still search for +them. ~.noupdate~ is ignored when you start indexing with an empty database (such as directly after *mu init*). There also the option *--lazy-check* which can greatly speed up indexing; see below for details. -The first run of *mu index* may take a few minutes if you have a lot of mail (tens -of thousands of messages). Fortunately, such a full scan needs to be done only -once; after that it suffices to index the changes, which goes much faster. See -the `PERFORMANCE (i,ii,iii)' below for more information. +A first run of *mu index* may take a few minutes if you have a lot of mail (tens +or hundreds of thousands of messages). Fortunately, such a full scan needs to be +done only rarely; after that, it suffices to index just the changes, which goes +much faster. See *PERFORMANCE (i,ii,iii)* below for more information. -The optional `phase two' of the indexing-process is the removal of messages from -the database for which there is no longer a corresponding file in the Maildir. -If you do not want this, you can use *-n*, *--nocleanup*. +The optional cleanup-phase of the indexing-process is the removal of messages +from the database for which there is no longer a corresponding file in the +Maildir. If you do not want this, you can use *-n*, *--nocleanup*. When *mu index* catches one of the signals *SIGINT*, *SIGHUP* or *SIGTERM* (e.g., when you press *Ctrl-C* during the indexing process), it attempts to shutdown -gracefully; it tries to save and commit data, and close the database etc. If it -receives another signal (e.g., when pressing Ctrl-C once more), *mu index* will -terminate immediately. +gracefully: save and commit data and close the database etc. If it receives +another signal (e.g., when pressing Ctrl-C once more), *mu index* will terminate +immediately. * INDEX OPTIONS @@ -210,7 +211,7 @@ Indexing the the same 93000-message mail corpus with the last few releases: Quite some variation! Over time new features / refactoring can change the timings quite a bit. At -least for now, the latest code is both the fastest and the most featureful! +least for now, the latest code is both the fastest and the most feature-rich. #+include: "exit-code.inc" :minlevel 1