8c706a77db
When re-initializing the store, automatically write the labels to a file in mu's cache, so user can later import them.
162 lines
5.1 KiB
Org Mode
162 lines
5.1 KiB
Org Mode
#+TITLE: MU LABEL
|
||
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
||
#+include: macros.inc
|
||
|
||
* NAME
|
||
|
||
mu-label - attach labels to messages. Export labels to file, and import them.
|
||
|
||
* SYNOPSIS
|
||
|
||
*mu* [_COMMON-OPTIONS_] *label* update [UPDATE-OPTIONS] "<query>" --labels [{+,-}<label>]...
|
||
|
||
*mu* [_COMMON-OPTIONS_] *label* list [LIST-OPTIONS]
|
||
|
||
mu [_COMMON-OPTIONS_] *label* clear [CLEAR-OPTIONS] "<query>"
|
||
|
||
mu [_COMMON-OPTIONS_] *label* export [<file>]
|
||
|
||
mu [_COMMON-OPTIONS_] *label* import <file>
|
||
|
||
* DESCRIPTION
|
||
|
||
*mu label* is the sub-command for adding and removing and listing message labels.
|
||
|
||
A label is a string associated with a message.
|
||
|
||
*mu label* has five sub-commands (i.e., 'sub-sub-commands'):
|
||
|
||
- *update* for changing the labels for the messages matching some query
|
||
- *clear* for clearing all labels from messages matching some query
|
||
- *list* to list all labels that are in use in the store
|
||
- *export* to write the label information to a file
|
||
- *import* the read label information from a file
|
||
|
||
Unlike other message metadata stored by *mu*, labels _cannot_ be restored by
|
||
re-indexing messages. Hence, to avoid loosing label information, you must *export*
|
||
it before re-indexing, and *import* afterwards.
|
||
|
||
* UPDATE OPTIONS
|
||
|
||
The *update* command changes the labels for messages that match some query. Make sure the query is recognized as a single parameter, i.e., quote it when using from a shell.
|
||
|
||
** --labels
|
||
|
||
a comma-separated list of labels, each prefixed with either *+* to add that
|
||
label, or *-* to remove it. See *VALID LABELS*.
|
||
|
||
** --dry-run
|
||
|
||
only print what /would/ change, but do not change anything
|
||
|
||
#+include: "muhome.inc" :minlevel 2
|
||
|
||
* CLEAR OPTIONS
|
||
|
||
The *clear* command removes all labels from messages that match some query. Make
|
||
sure the query is recognized as a single parameter, i.e., quote it when using
|
||
from a shell.
|
||
|
||
** --dry-run
|
||
|
||
only print what would change, but do not change anything
|
||
|
||
#+include: "muhome.inc" :minlevel 2
|
||
|
||
* LIST OPTIONS
|
||
|
||
The *list* command lists all the labels that are currently in use in the store.
|
||
|
||
|
||
* EXPORT OPTIONS
|
||
|
||
The *export* command outputs /all/ labels in the store to a file, so you can *import*
|
||
it later. The command takes a path to a file or a directory (ending in '/') as
|
||
its argument.
|
||
|
||
If a file is specified, *mu* writes the export to it.
|
||
|
||
If a directory is specified, *mu* writes to a file in that directory. The directory must already exist.
|
||
|
||
When neither is specified, *mu* writes to a file in the current directory.
|
||
|
||
See *EXPORT FORMAT* below for details about the format.
|
||
|
||
* IMPORT OPTIONS
|
||
|
||
The *import* command is for restoring the labels from a file created through
|
||
*export* earlier. The command takes a path to a file as its argument.
|
||
|
||
See *EXPORT FORMAT* below for details on the format.
|
||
|
||
** --dry-run
|
||
|
||
only print what would change, but do not change anything
|
||
|
||
#+include: "muhome.inc" :minlevel 2
|
||
|
||
* VALID LABELS
|
||
|
||
*mu* does not wish to limit your creativity, but nevertheless puts a few
|
||
restrictions on what is accepted as a label:
|
||
|
||
- a *valid label character* is either a UTF-8 encoded alphanumeric character, or
|
||
any ASCII character that is not a control-character and is not one of ' '
|
||
(SPC), ',', '"', '/', '\' '*', '$'.
|
||
- a *valid label* consists of one or more valid label characters, the first of
|
||
which must *not* be either '+' or '-'
|
||
|
||
Hence, some valid labels are: ~project-x~, ~capybara~, ~fnorb~, while some _invalid_
|
||
ones are: ~holiday plan~ and ~+fancy$/dinner~.
|
||
|
||
* EXPORT FORMAT
|
||
|
||
The formats for import/export are UTF-8 encoded text. The first line starts with
|
||
~;;~ and some internal data. Empty lines are ignored.
|
||
|
||
Each entry represents the tags for a message. It consists of three lines. The
|
||
first starts with ~path:~ followed by the file-system path to the message. The
|
||
second line starts with ~message-id:~ followed by the message-id for the message.
|
||
Finally, the third line starts with ~tag:~ followed by space-separated tags for
|
||
the message
|
||
|
||
With this, the labels for a message can be restored.
|
||
|
||
#+begin_example
|
||
path:/home/user/Maildir/inbox/cur/1720645394.99f64f5d81f42ba4.hyperion:2,S
|
||
message-id:669338009127192q7821feh1t826d0c4c90bd8fdf@mail.gmail.com
|
||
labels:foo,bar,cuux
|
||
#+end_example
|
||
|
||
Note, the ~message-id:~ is only used if the message cannot be found at ~path:.
|
||
This adds some tolerance for the case where the precise file-system positions
|
||
have changed since the labels were exported. The upshot of that is that if there
|
||
are _duplicate_ messages (messages with the same message-id), the tags are applied
|
||
to all of them.
|
||
|
||
#+include: "exit-code.inc" :minlevel 1
|
||
|
||
* EXAMPLES
|
||
|
||
Some examples. For the query parameter, make sure to quote the query to ensure
|
||
it is recognized as a single parameter.
|
||
|
||
Remove the label "planet" and add the label "dwarf-planet" to all messages that
|
||
have "pluto" in their subject:
|
||
#+begin_export
|
||
$ mu label update "subject:pluto" --labels -planet,+dwarf-planet
|
||
#+end_export
|
||
|
||
|
||
Clear all labels from messages with the label "boring":
|
||
#+begin_export
|
||
$ mu label clear "label:boring"
|
||
#+end_export
|
||
|
||
#+include: "prefooter.inc" :minlevel 1
|
||
|
||
* SEE ALSO
|
||
|
||
{{{man-link(mu-query,1)}}},
|
||
{{{man-link(mu-find,1)}}},
|