165 lines
5.2 KiB
Org Mode
165 lines
5.2 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
|
||
|
||
Important: unlike other message metadata stored by *mu*, labels _cannot_ be restored
|
||
by merely re-indexing messages. Hence, to avoid loosing label information, you
|
||
must *export* it before re-indexing, and *import* afterwards.
|
||
|
||
* UPDATE OPTIONS
|
||
|
||
The *update* coxmmand changes the labels for messages that match some query. The
|
||
query must be recognized as a single parameter; hence, it must be quoted 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*.
|
||
|
||
*mu4e* users: note the difference, in *mu4e* the label expressions are
|
||
_space_-separated, here they are _comma_-separated.
|
||
|
||
** --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. As
|
||
with *update*, the query must be recognized as a single parameter, i.e., quote it
|
||
when using 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 takes the labels in the store and the messages they apply to,
|
||
and writes this information to a file. You can *import* this file later, to
|
||
restore the labels. 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 any character that is not a control-character, a
|
||
blank, or any of *'*, *"*, *`*, */*, *\*, *$*
|
||
- 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~, ~c@pybara~, ~fn😃rb~, 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
|
||
|
||
#+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 using ~path:~.
|
||
|
||
This adds some fault-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)}}},
|