mu4e/man/mu-labels.1.org

#+TITLE: MU LABELS
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc

* NAME

mu-labels - attach labels to messages. Export labels to file, and import them.

* SYNOPSIS

*mu* [​_COMMON-OPTIONS_​] labels update [​UPDATE-OPTIONS​] "<query>" --labels [{+,-}<label>]...

*mu* [​_COMMON-OPTIONS_​] labels list

*mu* [​_COMMON-OPTIONS_​] labels list-restore

*mu* [​_COMMON-OPTIONS_​] labels clear [CLEAR-OPTIONS] "<query>"

*mu* [​_COMMON-OPTIONS_​] labels export [<file>]

*mu* [​_COMMON-OPTIONS_​] labels import <file>

* DESCRIPTION

*mu labels* is the sub-command for adding and removing and listing message labels.

A label is a string associated with a message.

*mu labels* 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 used in the store
- *list-restore* to restore the list of labels from 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* command 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.
This is the information is used for auto-completion in *mu4e*.

With the (global, directly after *mu) *--verbose* option, this also includes the
counts.

* LIST-RESTORE OPTIONS

It is possible that the list of labels (as per the *list* sub-command) gets
outdated for various reasons. With *list-restore*, this list get refreshed with
the actual labels as seen 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, not
  a blank, nor anything matching the regular expression ~[^\"$',/\\`]~
- 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 UTF8-encoded text. The first line starts with
~;;~ and some internal data. Empty lines are ignored.

Each entry represents the labels for a message. Messages without labels are not
included.

An entry consists of three lines:
1. The first line starts with ~path:~ followed by the file-system path to the
   message.
2. The second line starts with ~message-id:~ followed by the message-id for the
   message.
3. Finally, the third line starts with ~labels:~ followed by the space-separated
   labels 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

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_example
$ mu labels update "subject:pluto" --labels -planet,+dwarf-planet
#+end_example

Clear all labels from messages with the label "boring":

#+begin_example
$ mu labels clear "label:boring"
#+end_example

#+include: "prefooter.inc" :minlevel 1

* SEE ALSO

{{{man-link(mu-query,1)}}},
{{{man-link(mu-find,1)}}},