.\"
.\" FreeBSD pkg - a next generation package for the installation and maintenance
.\" of non-core utilities.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\"
.\" @(#)pkg.8
.\"
.Dd May 17, 2014
.Dt PKG-ANNOTATE 8
.Os
.Sh NAME
.Nm "pkg annotate"
.Nd add, modify or delete arbitrary annotations from packages
.Sh SYNOPSIS
.Nm
.Op Fl qy
.Fl A|M
.Op Fl Cgix
.Ar pkg-name
.Ar tag
.Op Ar value
.Nm
.Op Fl qy
.Fl S|D
.Op Fl Cgix
.Ar pkg-name
.Ar tag
.Nm
.Op Fl qy
.Fl a
.Fl A|M
.Ar tag
.Op Ar value
.Nm
.Op Fl qy
.Fl a
.Fl S|D
.Ar tag
.Pp
.Nm
.Op Cm --{quiet,yes}
.Cm --{add|modify}
.Op Cm --{case-sensitive,case-insensitive,glob,regex}
.Ar pkg-name
.Ar tag
.Op Ar value
.Nm
.Op Cm --{quiet,yes}
.Cm --{show|delete}
.Op Cm --{case-sensitive,case-insensitive,glob,regex}
.Ar pkg-name
.Ar tag
.Nm
.Op Cm --{quiet,yes}
.Cm --all
.Cm --{add|modify}
.Ar tag
.Op Ar value
.Nm
.Op Cm --{quiet,yes}
.Cm --all
.Cm --{show|delete}
.Ar tag
.Sh DESCRIPTION
.Nm
is used to add, modify, delete or show package annotations.
These are freeform tag-value pairs which may contain any arbitrary text.
.Ar Tags
must be unique per package, but there is no restriction on what
text
.Ar values
may be attached to them.
.Pp
The
.Ar tag
is always specified on the command line, but when adding or modifying
an annotation, the
.Ar value
may be supplied either on the command line or as a text stream on stdin.
.Sh OPTIONS
The following options are supported by
.Nm :
.Bl -tag -width modify
.It Fl a , Cm --all
Annotate all installed packages.
.It Fl A , Cm --add
The operation is to add a new annotation.
Attempting to add an annotation with a
.Ar tag
that already applies to that package is an error, but this will not
cause
.Nm
to exit before attempting to apply the annotation to all remaining
matched packages.
.It Fl C , Cm --case-sensitive
Make the standard or the regular expression
.Fl ( x )
matching against
.Ar pkg-name
case sensitive.
.It Fl D , Cm --delete
The operation is to delete an annotation.
Only the
.Ar tag
needs to be specified.
Attempting to delete an annotation which does not exist on a package
is an error, but this will not prevent
.Nm
carrying on to delete the annotation from all matched packages.
.It Fl g , Cm --glob
Treat
.Ar pkg-name
as a shell glob pattern.
.It Fl i , Cm --case-insensitive
Make the standard or the regular expression
.Fl ( x )
matching against
.Ar pkg-name
case insensitive.
This is the default, unless modified by setting
.Ev CASE_SENSITIVE_MATCH
to true in
.Pa pkg.conf .
.It Fl M , Cm --modify
The operation is to modify a previously existing annotation.
Functionally, this behaves similarly to
.Fl A
except that it will succeed irrespective of whether the tag already
applies to all the matched packages.
.It Fl q , Cm --quiet
Operate quietly: do not output anything other than confirmatory questions.
.It Fl S , Cm --show
Display the annotation identified by
.Ar tag
for each matched package.
.It Fl x , Cm --regex
Treat
.Ar pkg-name
as a regular expression according to the "modern" or "extended" syntax
of
.Xr re_format 7 .
.It Fl y , Cm --yes
Assume "yes" as the answer to all questions.
.El
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm .
See
.Xr pkg.conf 5
for further description.
.Bl -tag -width ".Ev NO_DESCRIPTIONS"
.It Ev PKG_DBDIR
.It Ev DEFAULT_ALWAYS_YES
.It Ev ASSUME_ALWAYS_YES
.It Ev CASE_SENSITIVE_MATCH
.El
.Sh FILES
See
.Xr pkg.conf 5 .
.Sh EXAMPLES
Annotate the nginx package with the tag foo and a value of bar:
.Dl # pkg annotate -A nginx foo bar
.Pp
View all annotations on a package:
.Dl $ pkg info nginx
.Pp
Remove the annotation:
.Dl # pkg annotate -D nginx foo
.Pp
Show all packages with the foo annotation:
.Dl # pkg annotate --all --show foo
.Pp
.\" ---------------------------------------------------------------------------
.Sh SEE ALSO
.Xr pkg_create 3 ,
.Xr pkg_printf 3 ,
.Xr pkg_repo_create 3 ,
.Xr pkg_repos 3 ,
.Xr pkg-keywords 5 ,
.Xr pkg-lua-script 5 ,
.Xr pkg-repository 5 ,
.Xr pkg-script 5 ,
.Xr pkg-triggers 5 ,
.Xr pkg.conf 5 ,
.Xr pkg 8 ,
.Xr pkg-add 8 ,
.Xr pkg-alias 8 ,
.Xr pkg-audit 8 ,
.Xr pkg-autoremove 8 ,
.Xr pkg-check 8 ,
.Xr pkg-clean 8 ,
.Xr pkg-config 8 ,
.Xr pkg-create 8 ,
.Xr pkg-delete 8 ,
.Xr pkg-fetch 8 ,
.Xr pkg-info 8 ,
.Xr pkg-install 8 ,
.Xr pkg-key 8 ,
.Xr pkg-lock 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 8 ,
.Xr pkg-repositories 8 ,
.Xr pkg-rquery 8 ,
.Xr pkg-search 8 ,
.Xr pkg-set 8 ,
.Xr pkg-shell 8 ,
.Xr pkg-shlib 8 ,
.Xr pkg-ssh 8 ,
.Xr pkg-stats 8 ,
.Xr pkg-triggers 8 ,
.Xr pkg-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-version 8 ,
.Xr pkg-which 8
