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

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.

SEE ALSO

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