diff --git a/man/mu-label.1.org b/man/mu-label.1.org index ac83d02e..9c3cdcba 100644 --- a/man/mu-label.1.org +++ b/man/mu-label.1.org @@ -32,19 +32,24 @@ A label is a string associated with a message. - *export* to write the label information to a file - *import* the read label information from a file -Unlike other message metadata stored by *mu*, labels _cannot_ be restored by -re-indexing messages. Hence, to avoid loosing label information, you must *export* -it before re-indexing, and *import* afterwards. +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. Make sure the query is recognized as a single parameter, i.e., quote it when using from a shell. +The *update* coxmmand 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 @@ -53,13 +58,13 @@ The *update* command changes the labels for messages that match some query. Make * CLEAR OPTIONS -The *clear* command removes all labels from messages that match some query. Make -sure the query is recognized as a single parameter, i.e., quote it when using -from a shell. +The *clear* command removes all labels from messages that match some query. As +with *update*, the must be recognized as a single parameter, i.e., quote it when +using from a shell. ** --dry-run - only print what would change, but do not change anything + only print what /would/ change, but do not change anything #+include: "muhome.inc" :minlevel 2 @@ -67,16 +72,17 @@ from a shell. The *list* command lists all the labels that are currently in use in the store. - * EXPORT OPTIONS -The *export* command outputs /all/ labels in the store to a file, so you can *import* -it later. The command takes a path to a file or a directory (ending in '/') as -its argument. +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. +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. @@ -119,19 +125,18 @@ second line starts with ~message-id:~ followed by the message-id for the message Finally, the third line starts with ~tag:~ followed by space-separated tags for the message -With this, the labels for a message can be restored. - #+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 -Note, the ~message-id:~ is only used if the message cannot be found at ~path:. -This adds some 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. +Note, 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 @@ -146,7 +151,6 @@ have "pluto" in their subject: $ mu label update "subject:pluto" --labels -planet,+dwarf-planet #+end_export - Clear all labels from messages with the label "boring": #+begin_export $ mu label clear "label:boring"