mu4e/man/mu-labels.1.org

MU LABELS

• NAME
• SYNOPSIS
• DESCRIPTION
• UPDATE OPTIONS
  • –labels
  • -n, –dry-run
• CLEAR OPTIONS
  • -n, –dry-run
• LIST OPTIONS
• RESTORE-LIST OPTIONS
• EXPORT OPTIONS
• IMPORT OPTIONS
  • -n, –dry-run
• VALID LABELS
• EXPORT FORMAT
  • Import using message-id
• EXAMPLES
• SEE ALSO

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 restore-list

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
• restore-list to restore the list of labels from the database (store)
• export to write the label information to a file
• import to 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.

-n, –dry-run

only print what would change, but do not change anything

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.

-n, –dry-run

only print what would change, but do not change anything

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.

RESTORE-LIST OPTIONS

It is possible that the list of labels (as per the list sub-command) gets outdated for various reasons. With restore-list, this list gets 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.

-n, –dry-run

only print what would change, but do not change anything

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

path:/home/user/Maildir/inbox/cur/1720645394.99f64f5d81f42ba4.hyperion:2,S
message-id:669338009127192q7821feh1t826d0c4c90bd8fdf@mail.gmail.com
labels:foo,bar,cuux

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.

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:

$ mu labels update "subject:pluto" --labels -planet,+dwarf-planet

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

$ mu labels clear "label:boring"

SEE ALSO

,