This document was generated by the pacwrap binary with version 0.8.1-c243d52-RELEASE (30/04/2024) of the program.
pacwrap
pacwrap [OPERATION | VERB] [ARGUMENTS] [TARGETS]
A package management front-end which utilises libalpm to facilitate the creation of unprivileged, namespace containers with parallelised, filesystem-agnostic deduplication. These containers are constructed with bubblewrap to execute package transactions and launch applications.
This application is designed to allow for the creation and execution of secure, replicable containerised environments for general-purpose use. CLI and GUI applications are all supported. Once a container environment is configured, it can be re-established or replicated on any system.
Each long-option parameter can also be specified herein as a command verb for a matter of convenience. Additional command verb shortcuts are available and are documented alongside their relevancy.
Invoke a container to execute the provided command sequence.
Synchronize package databases and containers in aggregate.
Remove packages from target containers in aggregate.
Compose a container from configuration.
Query package information from target container.
Manage and show status of running container processes.
List available containers managed by pacwrap.
Engage miscellaneous utilities to manage containers.
Display version banner or information.
Print the help manual to STDOUT.
Invoke a container to execute the provided command sequence. Command verb run provides a
shortcut to this module.
Container name to spawn an instance of, along with the proceeding command-line sequence to execute. execute. All command-line parameters after the container name are passed through to execute inside of the container environment.
Invoke a bash shell in the target container. Command verb shell provides a shortcut
to this module with this option.
Execute the provided command sequence with fakeroot and fakechroot.
Launch firefox inside an instance of the firefox container.
Open a fakeroot bash shell inside an instance of the base container.
Provides the facilities required to be able to synchronize and create containers in aggregate.
Synchronize remote package databases. Specify up to 2 times to force a refresh.
Execute aggregate upgrade routine on all or specified containers. Use -t, --target[=CONTAINER] followed
by a list of packages to specify package targets. Packages applicable to a target must only be specified
after the target operand.
Create a container with the first specified target. A container type argument is also required. Command verb
init provides a shortcut to the synchronization module, equivalent to specifying the options -Syuc.
Base container type. Specify alongside -c, --create to assign this container type during creation.
This container type is used as the base layer for all downstream containers. Only one base container dependency per slice or aggregate is supported. Filesystem and package deduplication via slices and aggregate containers are recommended, but optional. This container type is not dependant.
Slice container type. Specify alongside -c, --create to assign this container type during creation.
Requires a base dependency, and optionally one or more sliced dependencies, to ascertain foreign packages and influence ordering of downstream synchronization target(s). Container slicing provides the ability to install packages in a lightweight, sliced filesytem, which aid in the deduplication of common downstream package and filesystem dependencies.
Useful for graphics drivers, graphical toolkits, fonts, etc.; these are not meant for applications.
Aggregate container type. Specify alongside -c, --create to this assign container type during creation.
Requires a base dependency, and optionally one or more sliced dependencies, in order to acertain foreign packages and amalgamate the target. These containers are ideal for installing software with the aid of filesystem and package deduplication.
Useful for all general purpose applications, browsers, e-mail clients, or even terminal user interface applications such as IRC clients. It is recommended to base your containers on aggregate type containers.
Declare a target container for the specified operation, followed by a list of package target(s).
Force execution of filesystem synchronization target on all or specified containers. In combination with -o/--target-only, in addition to no other specified targets, filesystems will be synchronized without package synhcronization on on all applicable containers. This operation is useful for propagation of manual filesystem changes to all aggregate containers.
Apply specified operation on the specified target(s) only.
Specify dependencies for a container create operation.
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified. Only applicable to pre-existing targets and not create operations.
Enable lazy-database initialization for this transaction. NOTE: This feature is experimental.
Edge cases exist wherein the use of --force-foreign may be required.
Force synchronization of foreign packages on resident container. Useful for when installing a new package in an aggregate container without all the prerequisite foreign dependencies synchronized to the resident container's package database.
Transact on resident containers with a database-only transaction.
Override confirmation prompts and confirm all operations.
Synchronize remotes and create a base-type container named base with no additional packages.
Synchronize remote databases, create two sliced containers, one named common with the packages
gtk3, qt6-base, and another named nvidia with the package nvidia-utils.
Synchronize remote databases and upgrade container dependencies, then create aggregate container
named mozilla with the package firefox.
Install thunderbird in the target container mozilla.
Synchronize filesystem state of all associated containers present in the data directory.
Remove packages from specified containers.
Recursively remove all target packages with the associated target container. This does not apply to packages upstream of a downstream container.
Remove all target packages with the associated target container, including all their associated dependencies, provided they are not required by other packages, and are not marked as being upstream of the target container.
Specify a target container for the specified operation. At least one container target is is required for package removal operations.
Force the removal of foreign packages on target container. Useful for cleaning up the package database of foreign, upstream dependencies synchronized to the target container's package database.
Delete root filesystem(s) of specified targets. Shortcout to -Ur.
Preview operation and perform no transaction.
Transact on resident containers with a database-only transaction.
Override confirmation prompts and confirm all operations.
Remove the target package firefox from target container firefox.
Delete the root filesystem for the firefox container.
Compose containers from container configuration files. This functionality provides a way to deterministically compose containers from an established configuration.
Compose a container from the specified configuration file on disk. Unless a target is otherwise specified, the container will be initialized with a name derived from the filename provided.
Compose an available, existing container for composition. The pre-existing container root will be deleted and the container will be composited from the configuration data enumerated.
Specify a target container for the specified operation.
Disable sanity checks and force removal of container filesystem(s).
Queues all available, existing containers for composition. All pre-existing container roots will be deleted and composited from the available configuration data enumerated.
Enable lazy-database initialization for this transaction. NOTE: This feature is experimental.
Edge cases exist wherein the use of --force-foreign may be required.
Instruct pacwrap to populate configuration data from uninitialized containers. Under normal circumstances, configuration data will only be populated from containers with configuration data and an associative container root present. This option engages an alternate enuermation pathway to allow composition of dormant, uninitialized container configurations.
Override confirmation prompts and confirm all operations.
Reinitialize an existing container named element with its configuration derived from the file 'element.yml'.
Reinitialize all container configurations available in '$PACWRAP_CONFIG_DIR/container/'.
Query package list on target container.
Quiet the output by truncating the package string.
Specify a target container for the specified operation.
Filter output to explicitly-marked packages.
Print a list of explicit packages from the base container to STDOUT.
Table a process list of running containers. Containers may be filtered on target and process depth.
Enumerate a process summary of containers instantiated by pacwrap.
Enumerate a process id list of containers instantiated by pacwrap.
Kill target containers and their associated processes.
Target all containers and enumerate their associated processes.
Enumerate all processes at the specified depth associated with running containers.
Specify a target container for the specified operation.
Override confirmation prompts and confirm all operations.
Print table enumerating all container processes to STDOUT with process arguments and execution path split into separate columns.
Enumerate container processes with ps via encapsulating an enumeration of pids from all instances
into a space-delimited bash string.
List all initialized containers presently managed by pacwrap.
This command module is a shortcut to -Ul. Command verb ls also is a
shortcut to this command module.
Display a total column.
Display a size on disk column.
Toggle byte unit display.
Print container tabulation out to STDOUT with two total columns, one listing the container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
Print container tabulation to STDOUT with three total columns, first listing the container name, second the total amount of bytes, and the last showing the total with byteunits. Then print a summation of total, actual consumption below.
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and maintenance of containers. Each utility is considered a command module and therefore can be shortcuted with a command verb.
Create desktop file to launch application inside of a pacwrap container.
Invoke $EDITOR to view file associated with pacwrap.
Invoke $EDITOR to edit file associated with pacwrap.
Invoke default file viewer on specified target's home or root directory.
Print a list of containers and basic metrics.
Create a symbolic container.
Delete a container(s) root filesystem.
Create and manage desktop files to launch applications in pacwrap from your favourite applications menu.
Create desktop file associated with application at $HOME/.local/share/applications/ launching an
application in pacwrap.
List available desktop files in the container root located at /usr/share/applications/.
Remove desktop file associated with application from $HOME/.local/share/applications/.
These options are associated with the --edit and --view utility command modules.
Edit specified container configuration located in the pacwrap data directory. Defaults to the primary configuration file: '$PACWRAP_CONFIG_DIR/pacwrap.yml' if no option is otherwise specified.
Edit specified desktop file associated with a pacwrap container.
Edit repositories configuration file: $PACWRAP_CONFIG_DIR/repositories.conf.
View 'pacwrap.log'. This file contains transaction log iformation.
These options are associated with the --open utility command module.
Specified container's home filesystem.
Specified container's root filesystem.
Target container to perform the operation.
These options are associated with the --list utility command module.
Display a total column.
Display a size on disk column.
Print out a summary table to STDOUT.
Toggle byte unit display for the proceeding item.
These options are associated with the --remove utility command module.
Target container to perform the operation.
Peform the operation without confirmation.
Disable sanity checks and force removal of conatiner filesystem.
These options are associated with the --symlink utility command module.
Create a symbolic container of target at destination.
Create a fresh configuration rather than derive it from the target.
Open firefox's home directory in the default file manager.
View **$PACWRAP_DATA_DIR**/pacwrap.log with $EDITOR.
Edit $PACWRAP_CONFIG_DIR**/container/firefox.yml with $EDITOR.
Create desktop file $HOME/.local/share/applications/pacwrap.firefox.desktop derived from
/usr/share/applications/firefox.desktop in the root of the firefox container.
Create a symbolic container called runelite of java.
Print container tabulation out to STDOUT with two total columns, one listing the container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
Print container tabulation to STDOUT with three total columns, first listing the container name, second the total amount of bytes, and the last showing the total with byteunits. Then print a summation of total, actual consumption below.
Sends version information to STDOUT with colourful ASCII art. The 'min' option provides a minimalistic output as is provided to non-colour terms.
Print the specified topic to STDOUT.
When specifying a topic to display, show the default topic in addition to specified options.
Change output format of help in STDOUT. Format options include: 'ansi', 'dumb', 'markdown', and 'man'. This option is for the express purposes of generating documentation at build time, and has little utility outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages.
Display all help topics.
Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters. All environment variables listed are case sensitive.
Use with care: These variables if used improperly could result in undesired behaviour.
Set path of the configuration directory, overriding the default location.
Set path of the data directory, overriding the default location.
Set path of the cache directory, overriding the default location.
Upon container invocation, mount the set path provided when engaging the home filesystem module.
Upon container invocation, mount the set path provided when engaging the root filesystem module.
Toggle verbose output during a transaction. Valid options are 1 for enablement and 0 for
disablement of verbosity.
For the following environment variables, contained herein are default runtime values. Any variables not included here in this subsection are to be assumed to have inert values by default.
$HOME/.cache/pacwrap: Default cache directory.
$HOME/.config/pacwrap: Default configuration directory.
$HOME/.local/share/pacwrap: Default data directory.
Copyright (C) 2023-2024 Xavier Moffett sapphirus@azorium.net
This program may be freely redistributed under the terms of the GNU General Public License v3 only.