.Dd July 21, 2024
.Dt tagger 1
.Os
.Sh NAME
.Nm tagger
.Nd Show and edit file system tags, stored as extended attribute
.Sh SYNOPSIS
.Nm
.Fl h
.Nm
.Fl \-version
.Nm
.Op Fl a Ar tag
.Op Fl d Ar tag
.Op Fl c Ar tag Fl i Ar tag
.Op Fl l
.Op Fl s
.Op Ar
.Sh DESCRIPTION
On Linux file systems that support extended attributes, the XDG desktop uses the
attribute `user.xdg.tags' to store a comma-separated list of user-defined tags.
File browsers such as Dolphin on KDE have user interface to manipulate them.
Unfortunately, it is inconvenient if one wishes to change tags for many files or
directories at once.
The
.Nm
tool allows you to list and/or edit tags in bulk, with a convenient command line
interface.
.Pp
If you add, change, and delete tags from files and/or directories in a single
command,
.Nm
will first delete tags, then apply changes, and finally add tags, in that order.
.Pp
The options are as follows:
.Ss General Options
.Bl -tag -width Ds
.It Fl h, \-help
Print help text and exit.
.It Fl \-version
Print version info and exit.
.El
.Ss Listing tags
.Bl -tag -width Ds
.It Fl l, \-list
List tags.
If you also specify any
.Sx Editing Options
(see below),
.Nm
reports tags before and after applying any changes.
.El
.Ss Editing Options
.Bl -tag -width Ds
.It Fl a, \-add Ar tag
Add the specified tag.
This option can be used multiple times.
.It Fl c, \-change Ar tag
Change the given tag, into a new value supplied as an argument for the
.Fl i
option (see below).
.It Fl i, \-into Ar tag
Change the value given with the last
.Fl c
option into the new value given here.
These pairs of
.Fl c
and
.Fl i
options can be used multiple times.
.It Fl d, \-delete Ar tag
Delete the given tag, if it exists.
This option can be used multiple times.
.It Fl s, \-sort
With this flag, changes will be written back for the file or directory in
alphabetically sorted order.
.El
.Sh ENVIRONMENT
.Nm
uses libscterm for its color output support, and as such honors the NO_COLOR
environment variable, if defined and non-empty.
Color output is also automatically suppressed when it is not written to a tty,
such as when writing to a pipe, or when using output redirection.
.Sh EXIT STATUS
.Nm
exits 0 on success, and 1 if an error occurs.
.Sh EXAMPLES
To change `Biografie' into `Biography' in all files in the current directory,
but only if present:
.Pp
.Dl tagger -c Biografie -i Biography *
.Pp
List the tags in a file named `MyMovie.mp4':
.Pp
.Dl tagger -l MyMovie.mp4
.Pp
To delete all `foo' and `bar' tags from files, if present:
.Pp
.Dl tagger -d foo -d bar *
.Pp
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.Sh SEE ALSO
.Xr xattr 7
.Sh AUTHORS
Bob Polis