cave

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.

	Introduction	cave
	Bugs, Requests, Support
	Overview
	FAQ
	Clients
	Configuration
	API