.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
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 of 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.
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
.\" .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