FreeBSD Manual Pages
MU LABELS(1) General Commands Manual MU LABELS(1) NAME mu-labels - attach labels to messages. Export labels to file, and im- port 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 mes- sage 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 --muhome Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Ear- lier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu. The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. 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 parame- ter, i.e., quote it when using a shell. --dry-run only print what would change, but do not change anything --muhome Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Ear- lier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu. The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. 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 in- cludes 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 re- freshed 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 direc- tory. 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 argu- ment. See EXPORT FORMAT below for details on the format. --dry-run only print what would change, but do not change anything --muhome Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Ear- lier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu. The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. 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 expres- sion [^ -- 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, fnrb, while some in- valid 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. EXIT CODE This command returns 0 upon successful completion, or a non-zero exit code otherwise. 0. success 2. no matches found. Try a different query 11. database schema mismatch. You need to re-initialize mu, see mu- init(1) 19. failed to acquire lock. Some other program has exclusive access to the mu database 99. caught an exception 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 mes- sages 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" REPORTING BUGS Please report bugs at https://github.com/djcb/mu/issues. AUTHOR Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> COPYRIGHT This manpage is part of mu 1.12.15. Copyright 2008-2026 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL ver- sion 3 or later https://gnu.org/licenses/gpl.html. This is free soft- ware: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. SEE ALSO mu-query(1), mu-find(1), MU LABELS(1)
NAME | SYNOPSIS | DESCRIPTION | UPDATE OPTIONS | CLEAR OPTIONS | LIST OPTIONS | LIST-RESTORE OPTIONS | EXPORT OPTIONS | IMPORT OPTIONS | VALID LABELS | EXPORT FORMAT | EXIT CODE | EXAMPLES | REPORTING BUGS | AUTHOR | COPYRIGHT | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mu-labels&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>