aboutsummaryrefslogtreecommitdiff
path: root/src/clients/cave/cave.txt
blob: 05c64a367a4790ab4c3820aa7d0d376fb9d0cb95 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
cave(1)
=======


NAME
----

cave - A commandline client for the other package mangler.

SYNOPSIS
--------

*cave [ --environment class:suffix ] [ --log-level level ] COMMAND [ARGS...]*

*cave help [ --all ]*

DESCRIPTION
-----------
The front-end to a number of commands.

For the COMMAND argument, see \'cave help' for a list of common commands, or
\'cave help --all' for all commands. To see documentation for a command named
\'foo', use \'man cave-foo'.


In addition to built-in commands, cave will also look in the directories named
in the colon-separated CAVE_COMMANDS_PATH environment variable, or, if unset,
\'/usr/libexec/cave/commands'. Any executables in this path will also be
available as commands (with any file extension stripped); these executables
may use the $CAVE environment variable to get access to the main cave program.


Arguments specified after the COMMAND are handled by the individual commands.
Arguments before the COMMAND are global arguments shared by all commands.


OPTIONS
-------
Global Options
~~~~~~~~~~~~~~
Global options, used by every subcommand.

*-E , --environment*::
        Environment specification (class:suffix, both parts optional)

*-L , --log-level*::
        Specify the log level

    *debug (d)*;;
        Show debug output (noisy)

    *qa (q)*;;
        Show QA messages and warnings only (default)

    *warning (w)*;;
        Show warnings only

    *silent (s)*;;
        Suppress all log messages (UNSAFE)


*-c , --colour*::
        Specify whether to use colour

    *auto (a)*;;
        Yes if stdout is connected to a terminal (default)

    *yes (y)*;;
        Yes

    *no (n)*;;
        No


*-h , --help*::
        display help message

*-v , --version*::
        display version information

CORE COMMANDS
-------------

config::
Perform post-install configuration on a package. Note that most packages do
not provide a post-install configuration script.

contents::
Display the contents of (files installed by) a given package ID.

fix-linkage::
Identifies packages with broken linkage that can be fixed by rebuilds. If
instructed, then executes the relevant install and uninstall actions to do
said fixing.

help::
Display help information for a particular command.

import::
Import a package from a directory containing its image. A named directory is
treated as holding the contents to install, and a dummy package name is
provided on the command line. Safe merge, unmerge, upgrade and replace support
is provided, as is content tracking for installed files.

info::
Displays a formatted summary of configuration and package information, e.g.
for use when submitting bug reports. The package names of any relevant
packages for bug reports should be passed as parameters.

owner::
Shows package IDs owning a given file.

purge::
Uninstalls any package that is not either in \'world' or a dependency of a
package in \'world'.

report::
Displays a formatted summary of potential problems with installed packages.

resolve::
Displays how to resolve one or more targets. If instructed, then executes the
relevant install and uninstall actions to perform that resolution.

resume::
Resumes a failed resultion from \'cave resolve'. To enable resumes, use \'cave
resolve --resume-file state --execute', and then if errors occur, use \'cave
resume --resume-file state [ --retry-failed ] [ --retry-skipped ]' to try
again.

search::
Searches for packages with particular characteristics.

show::
Displays a formatted summary of a given object. If the object is a set, the
set's contents are listed. If the object is a repository name, information
about the repository is displayed. If the object is a package dep spec with
wildcards, possible expansions are shown. If the object is a package dep spec
without wildcards, information about matching IDs are shown.

sync::
Syncs repositories. If any repository names are specified, these repositories
are synced. Otherwise, all syncable repositories are synced.

uninstall::
Uninstalls one or more packages. Note that \'cave uninstall' simply rewrites
the supplied dependency specifications and then uses \'cave resolve' to do the
work; \'cave uninstall foo' is the same as \'cave resolve !foo'.

SUPPLEMENTAL COMMANDS
---------------------

dump-cave-formats-conf::
Outputs suitable contents for ~/.cave/formats.conf. This file can be used to
customise the output format for many cave commands (although not commands
designed for script use, such as print-*).

executables::
Display executables belonging to an ID.

fix-cache::
Fixes on-disk caches. Normally this is handled automatically when needed (e.g.
after a sync, or when a package is installed), but a forced fix-cache is
required after a different package manager has been used, or if a repository
is modified without a sync.

generate-metadata::
Pregenerates metadata for a set of IDs.

manage-search-index::
Manages a search index for use by cave search. A search index is only valid
until a package is installed or uninstalled, or a sync is performed, or
configuration is changed.

size::
Shows the size of files installed by a package.

sync-protocol-options::
Displays options for a given sync protocol.

update-world::
Adds or removes items from the world set. This command is only for changing
the contents of the world set; it does not install or uninstall anything.

verify::
Verify than an installed package's files haven't changed. Note that there are
legitimate reasons for some files (such as configuration files) to have been
changed after a merge, and that some packages may install files that are not
directly tracked by the package manager.

DEVELOPMENT COMMANDS
--------------------

digest::
Generates a digest file for a particular package in a particular repository.

mirror::
Fetches files for a set of IDs.

SCRIPTING COMMANDS
------------------

has-version::
Returns success if there is an installed package matching a particular spec.
Suitable for use in scripts.

print-best-version::
Prints the best installed version matching a particular spec. No formatting is
used, making the output suitable for parsing by scripts.

print-categories::
Prints a list of known categories. No formatting is used, making the output
suitable for parsing by scripts.

print-commands::
Prints a list of known cave commands. No formatting is used, making the output
suitable for parsing by scripts.

print-dependent-ids::
Prints a list of installed IDs that are dependent upon another installed ID.
No formatting is used, making the output suitable for parsing by scripts.

print-environment-metadata::
Prints environment metadata. No formatting is used, making the output suitable
for parsing by scripts.

print-id-actions::
Prints ID actions. No formatting is used, making the output suitable for
parsing by scripts.

print-id-contents::
Prints a list of the contents of a given ID. No formatting is used, making the
output suitable for parsing by scripts.

print-id-environment-variable::
Prints ID environment variables. No formatting is used, making the output
suitable for parsing by scripts.

print-id-executables::
Prints a list of executables belonging to an ID. No formating is used, making
the script suitable for parsing by scripts.

print-id-masks::
Prints ID masks. No formatting is used, making the output suitable for parsing
by scripts.

print-id-metadata::
Prints ID metadata. No formatting is used, making the output suitable for
parsing by scripts.

print-id-size::
Prints the size of files installed by a package. No formatting is used, making
the output suitable for parsing by scripts.

print-ids::
Prints a list of known IDs. No formatting is used, making the output suitable
for parsing by scripts.

print-owners::
Prints a list of package IDs owning a given file. No formatting is used,
making the output suitable for parsing by scripts.

print-packages::
Prints a list of package names. No formatting is used, making the output
suitable for parsing by scripts.

print-repositories::
Prints a list of repositories. No formatting is used, making the output
suitable for parsing by scripts.

print-repository-formats::
Prints a list of available repository formats. No formatting is used, making
the output suitable for parsing by scripts.

print-repository-metadata::
Prints repository metadata. No formatting is used, making the output suitable
for parsing by scripts.

print-set::
Prints the contents (packages or other sets) of a given set.

print-sets::
Prints a list of sets. No formatting is used, making the output suitable for
parsing by scripts.

print-spec::
Parses a dependency spec and prints it out, possibly after applying certain
modifications. No formatting is used, making the output suitable for parsing
by scripts.

print-sync-protocols::
Prints a list of sync protocols. No formatting is used, making the output
suitable for parsing by scripts.

print-unused-distfiles::
Prints all distfiles not used by any installed package. No formatting is used,
making the output suitable for parsing by scripts.

INTERNAL COMMANDS
-----------------

display-resolution::
Displays a dependency resolution created using \'cave resolve'. Mostly for
internal use; most users will not use this command directly.

execute-resolution::
Execute a dependency resolution created using \'cave resolve'. Mostly for
internal use; most users will not use this command directly.

find-candidates::
Finds a list of candidate packages for a search. Used by \'cave search'; not
generally called directly by end users. Note that this command will often
select candidates that do not actually match some of the supplied
restrictions; use \'cave match' to obtain accurate results.

graph-jobs::
Creates a Graphviz graph for jobs in a resolution created using \'cave
resolve'. Mostly for internal use; most users will not use this command
directly.

match::
Determines whether a particular package version has certain properties. Mostly
for use by \'cave search'; not generally for use by end users.

perform::
Perform an action upon a package. Not suitable for direct use, although it may
be useful in some more complex scripts.

ENVIRONMENT
-----------
CAVE_COMMANDS_PATH::
Colon-separated paths in which to look for additional commands.

SEE ALSO
--------
*cave-config*(1)
*cave-contents*(1)
*cave-fix-linkage*(1)
*cave-help*(1)
*cave-import*(1)
*cave-info*(1)
*cave-owner*(1)
*cave-purge*(1)
*cave-report*(1)
*cave-resolve*(1)
*cave-resume*(1)
*cave-search*(1)
*cave-show*(1)
*cave-sync*(1)
*cave-uninstall*(1)
*cave-dump-cave-formats-conf*(1)
*cave-executables*(1)
*cave-fix-cache*(1)
*cave-generate-metadata*(1)
*cave-manage-search-index*(1)
*cave-size*(1)
*cave-sync-protocol-options*(1)
*cave-update-world*(1)
*cave-verify*(1)
*cave-digest*(1)
*cave-mirror*(1)
*cave-has-version*(1)
*cave-print-best-version*(1)
*cave-print-categories*(1)
*cave-print-commands*(1)
*cave-print-dependent-ids*(1)
*cave-print-environment-metadata*(1)
*cave-print-id-actions*(1)
*cave-print-id-contents*(1)
*cave-print-id-environment-variable*(1)
*cave-print-id-executables*(1)
*cave-print-id-masks*(1)
*cave-print-id-metadata*(1)
*cave-print-id-size*(1)
*cave-print-ids*(1)
*cave-print-owners*(1)
*cave-print-packages*(1)
*cave-print-repositories*(1)
*cave-print-repository-formats*(1)
*cave-print-repository-metadata*(1)
*cave-print-set*(1)
*cave-print-sets*(1)
*cave-print-spec*(1)
*cave-print-sync-protocols*(1)
*cave-print-unused-distfiles*(1)
*cave-display-resolution*(1)
*cave-execute-resolution*(1)
*cave-find-candidates*(1)
*cave-graph-jobs*(1)
*cave-match*(1)
*cave-perform*(1)