#+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 six 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 database (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, since the information is not part of the message
files. 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 text encoded as UTF-8. 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 a comma-separated
   list of 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

** Import using message-id

The ~message-id:~ line is only used if the message cannot be found using ~path:~.

This helps for the case where the precise file-system are not precisely the same
as those used when exporting. This happens, for instance, when changes were made
to the message flags since the export. Or when trying to import on a different
machine with different paths.

In any case, when using the message-id for importing, any _duplicate_ messages
(messages with the same message-id), all get the same labels.

#+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)}}},