pkg-annotate.8
1 .\" 2 .\" FreeBSD pkg - a next generation package for the installation and maintenance 3 .\" of non-core utilities. 4 .\" 5 .\" Redistribution and use in source and binary forms, with or without 6 .\" modification, are permitted provided that the following conditions 7 .\" are met: 8 .\" 1. Redistributions of source code must retain the above copyright 9 .\" notice, this list of conditions and the following disclaimer. 10 .\" 2. Redistributions in binary form must reproduce the above copyright 11 .\" notice, this list of conditions and the following disclaimer in the 12 .\" documentation and/or other materials provided with the distribution. 13 .\" 14 .\" 15 .\" @(#)pkg.8 16 .\" 17 .Dd May 17, 2014 18 .Dt PKG-ANNOTATE 8 19 .Os 20 .Sh NAME 21 .Nm "pkg annotate" 22 .Nd add, modify or delete arbitrary annotations from packages 23 .Sh SYNOPSIS 24 .Nm 25 .Op Fl qy 26 .Fl A|M 27 .Op Fl Cgix 28 .Ar pkg-name 29 .Ar tag 30 .Op Ar value 31 .Nm 32 .Op Fl qy 33 .Fl S|D 34 .Op Fl Cgix 35 .Ar pkg-name 36 .Ar tag 37 .Nm 38 .Op Fl qy 39 .Fl a 40 .Fl A|M 41 .Ar tag 42 .Op Ar value 43 .Nm 44 .Op Fl qy 45 .Fl a 46 .Fl S|D 47 .Ar tag 48 .Pp 49 .Nm 50 .Op Cm --{quiet,yes} 51 .Cm --{add|modify} 52 .Op Cm --{case-sensitive,case-insensitive,glob,regex} 53 .Ar pkg-name 54 .Ar tag 55 .Op Ar value 56 .Nm 57 .Op Cm --{quiet,yes} 58 .Cm --{show|delete} 59 .Op Cm --{case-sensitive,case-insensitive,glob,regex} 60 .Ar pkg-name 61 .Ar tag 62 .Nm 63 .Op Cm --{quiet,yes} 64 .Cm --all 65 .Cm --{add|modify} 66 .Ar tag 67 .Op Ar value 68 .Nm 69 .Op Cm --{quiet,yes} 70 .Cm --all 71 .Cm --{show|delete} 72 .Ar tag 73 .Sh DESCRIPTION 74 .Nm 75 is used to add, modify, delete or show package annotations. 76 These are freeform tag-value pairs which may contain any arbitrary text. 77 .Ar Tags 78 must be unique per package, but there is no restriction on what 79 text 80 .Ar values 81 may be attached to them. 82 .Pp 83 The 84 .Ar tag 85 is always specified on the command line, but when adding or modifying 86 an annotation, the 87 .Ar value 88 may be supplied either on the command line or as a text stream on stdin. 89 .Sh OPTIONS 90 The following options are supported by 91 .Nm : 92 .Bl -tag -width modify 93 .It Fl a , Cm --all 94 Annotate all installed packages. 95 .It Fl A , Cm --add 96 The operation is to add a new annotation. 97 Attempting to add an annotation with a 98 .Ar tag 99 that already applies to that package is an error, but this will not 100 cause 101 .Nm 102 to exit before attempting to apply the annotation to all remaining 103 matched packages. 104 .It Fl C , Cm --case-sensitive 105 Make the standard or the regular expression 106 .Fl ( x ) 107 matching against 108 .Ar pkg-name 109 case sensitive. 110 .It Fl D , Cm --delete 111 The operation is to delete an annotation. 112 Only the 113 .Ar tag 114 needs to be specified. 115 Attempting to delete an annotation which does not exist on a package 116 is an error, but this will not prevent 117 .Nm 118 carrying on to delete the annotation from all matched packages. 119 .It Fl g , Cm --glob 120 Treat 121 .Ar pkg-name 122 as a shell glob pattern. 123 .It Fl i , Cm --case-insensitive 124 Make the standard or the regular expression 125 .Fl ( x ) 126 matching against 127 .Ar pkg-name 128 case insensitive. 129 This is the default, unless modified by setting 130 .Ev CASE_SENSITIVE_MATCH 131 to true in 132 .Pa pkg.conf . 133 .It Fl M , Cm --modify 134 The operation is to modify a previously existing annotation. 135 Functionally, this behaves similarly to 136 .Fl A 137 except that it will succeed irrespective of whether the tag already 138 applies to all the matched packages. 139 .It Fl q , Cm --quiet 140 Operate quietly: do not output anything other than confirmatory questions. 141 .It Fl S , Cm --show 142 Display the annotation identified by 143 .Ar tag 144 for each matched package. 145 .It Fl x , Cm --regex 146 Treat 147 .Ar pkg-name 148 as a regular expression according to the "modern" or "extended" syntax 149 of 150 .Xr re_format 7 . 151 .It Fl y , Cm --yes 152 Assume "yes" as the answer to all questions. 153 .El 154 .Sh ENVIRONMENT 155 The following environment variables affect the execution of 156 .Nm . 157 See 158 .Xr pkg.conf 5 159 for further description. 160 .Bl -tag -width ".Ev NO_DESCRIPTIONS" 161 .It Ev PKG_DBDIR 162 .It Ev DEFAULT_ALWAYS_YES 163 .It Ev ASSUME_ALWAYS_YES 164 .It Ev CASE_SENSITIVE_MATCH 165 .El 166 .Sh FILES 167 See 168 .Xr pkg.conf 5 . 169 .Sh EXAMPLES 170 Annotate the nginx package with the tag foo and a value of bar: 171 .Dl # pkg annotate -A nginx foo bar 172 .Pp 173 View all annotations on a package: 174 .Dl $ pkg info nginx 175 .Pp 176 Remove the annotation: 177 .Dl # pkg annotate -D nginx foo 178 .Pp 179 Show all packages with the foo annotation: 180 .Dl # pkg annotate --all --show foo 181 .Pp 182 .\" --------------------------------------------------------------------------- 183 .Sh SEE ALSO 184 .Xr pkg_create 3 , 185 .Xr pkg_printf 3 , 186 .Xr pkg_repo_create 3 , 187 .Xr pkg_repos 3 , 188 .Xr pkg-keywords 5 , 189 .Xr pkg-lua-script 5 , 190 .Xr pkg-repository 5 , 191 .Xr pkg-script 5 , 192 .Xr pkg-triggers 5 , 193 .Xr pkg.conf 5 , 194 .Xr pkg 8 , 195 .Xr pkg-add 8 , 196 .Xr pkg-alias 8 , 197 .Xr pkg-audit 8 , 198 .Xr pkg-autoremove 8 , 199 .Xr pkg-check 8 , 200 .Xr pkg-clean 8 , 201 .Xr pkg-config 8 , 202 .Xr pkg-create 8 , 203 .Xr pkg-delete 8 , 204 .Xr pkg-fetch 8 , 205 .Xr pkg-help 8 , 206 .Xr pkg-info 8 , 207 .Xr pkg-install 8 , 208 .Xr pkg-key 8 , 209 .Xr pkg-lock 8 , 210 .Xr pkg-plugins 8 , 211 .Xr pkg-query 8 , 212 .Xr pkg-register 8 , 213 .Xr pkg-repo 8 , 214 .Xr pkg-repositories 8 , 215 .Xr pkg-rquery 8 , 216 .Xr pkg-search 8 , 217 .Xr pkg-set 8 , 218 .Xr pkg-shell 8 , 219 .Xr pkg-shlib 8 , 220 .Xr pkg-ssh 8 , 221 .Xr pkg-stats 8 , 222 .Xr pkg-triggers 8 , 223 .Xr pkg-unregister 8 , 224 .Xr pkg-update 8 , 225 .Xr pkg-updating 8 , 226 .Xr pkg-upgrade 8 , 227 .Xr pkg-version 8 , 228 .Xr pkg-which 8