1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
#+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)}}},
|
