# NAME

`bpkg-pkg-unpack` – unpack package archive

# SYNOPSIS

`bpkg pkg-unpack [options] (pkg[/ver] | --existing|-e dir)`

# DESCRIPTION

If only the package name is specified, then the `pkg-unpack` command unpacks the archive for the previously fetched (`bpkg-pkg-fetch(1)`) package. The resulting package state is `unpacked` (`bpkg-pkg-status(1)`).

If the package version is also specified, then the (source) directory from one of the directory-based repositories (`bpkg-rep-add(1)`) is used in place, without copying it into the configuration directory. Such a package is called external.

If the `--existing|-e` option is used, then instead of the package name, `pkg-unpack` expects a local path to an existing package directory. In this case, `bpkg` will use the (source) directory in place, the same as for packages from directory-based repositories. Also, unless the `--purge|-p` option is specified, `bpkg` will not attempt to remove this directory when the package is later purged with the `bpkg-pkg-purge(1)` command. Such a package is also external.

If `--existing|-e` is specified together with the `--replace|-r` option, then `pkg-unpack` will replace the archive and/or source directory of a package that is already in the `unpacked` or `fetched` state.

An external package triggers several changes in semantics compared to a normal package: The package (output) directory inside the configuration is called just `pkg` rather than `pkg``-``ver`. It is also assumed that the packaging information (package manifest and lockfile) for such packages may change without incrementing the package version (for example, during development). To support this, `bpkg` implements the package iteration mechanism which may result in iteration numbers to be shown as part of the package version, for example, `1.2.3#1` (see Package Version).

# PKG-UNPACK OPTIONS

`--existing`|`-e`
  Treat the argument as an existing package directory path rather than the package name to unpack.
`--purge`|`-p`
  Remove the existing package directory when the package is purged.
`--replace`|`-r`
  Replace the source directory if the package is already unpacked or fetched. Can only be specified with an external package.
`--directory`|`-d` `dir`
  Assume configuration is in `dir` rather than in the current working directory.

# COMMON OPTIONS

The common options are summarized below with a more detailed description available in `bpkg-common-options(1)`.

`-v`
  Print essential underlying commands being executed.
`-V`
  Print all underlying commands being executed.
`--quiet`|`-q`
  Run quietly, only printing error messages.
`--verbose` `level`
  Set the diagnostics verbosity to `level` between 0 and 6.
`--stdout-format` `format`
  Representation format to use for printing to `stdout`.
`--jobs`|`-j` `num`
  Number of jobs to perform in parallel.
`--no-result`
  Don't print informational messages about the outcome of performing a command or some of its parts.
`--structured-result` `fmt`
  Write the result of performing a command in a structured form.
`--progress`
  Display progress indicators for long-lasting operations, such as network transfers, building, etc.
`--no-progress`
  Suppress progress indicators for long-lasting operations, such as network transfers, building, etc.
`--diag-color`
  Use color in diagnostics.
`--no-diag-color`
  Don't use color in diagnostics.
`--build` `path`
  The build program to be used to build packages.
`--build-option` `opt`
  Additional option to be passed to the build program.
`--fetch` `path`
  The fetch program to be used to download resources (packages, repository metadata, etc).
`--fetch-option` `opt`
  Additional option to be passed to the fetch program.
`--fetch-timeout` `sec`
  The fetch and fetch-like (for example, `git`) program timeout.
`--offline`
  Do not attempt to download resources (packages, repository metadata, etc), instead taking them from the local fetch cache if available and failing otherwise.
`--no-fetch-cache`
  Disable local caching of downloaded resources (packages, repository metadata, etc).
`--fetch-cache` `mode`
  Comma-separated list of local fetch cache modes.
`--fetch-cache-path` `dir`
  The directory of the local fetch cache.
`--fetch-cache-session` `id`
  The local fetch cache session.
`--pkg-proxy` `url`
  HTTP proxy server to use when fetching package manifests and archives from remote `pkg` repositories.
`--git` `path`
  The git program to be used to fetch git repositories.
`--git-option` `opt`
  Additional common option to be passed to the git program.
`--sha256` `path`
  The sha256 program to be used to calculate SHA256 sums.
`--sha256-option` `opt`
  Additional option to be passed to the sha256 program.
`--tar` `path`
  The tar program to be used to extract package archives.
`--tar-option` `opt`
  Additional option to be passed to the tar program.
`--openssl` `path`
  The openssl program to be used for crypto operations.
`--openssl-option` `opt`
  Additional option to be passed to the openssl program.
`--auth` `type`
  Types of repositories to authenticate.
`--trust` `fingerprint`
  Trust repository certificate with a SHA256 `fingerprint`.
`--trust-yes`
  Assume the answer to all authentication prompts is `yes`.
`--trust-no`
  Assume the answer to all authentication prompts is `no`.
`--git-capabilities` `up`=`pc`
  Protocol capabilities (`pc`) for a `git` repository URL prefix (`up`).
`--pager` `path`
  The pager program to be used to show long text.
`--pager-option` `opt`
  Additional option to be passed to the pager program.
`--options-file` `file`
  Read additional options from `file`.
`--default-options` `dir`
  The directory to load additional default options files from.
`--no-default-options`
  Don't load default options files.
`--keep-tmp`
  Don't remove the `bpkg`'s temporary directory at the end of the command execution and print its path at the verbosity level 2 or higher.

# DEFAULT OPTIONS FILES

See `bpkg-default-options-files(1)` for an overview of the default options files. For the `pkg-unpack` command the search start directory is the configuration directory. The following options files are searched for in each directory and, if found, loaded in the order listed:

    bpkg.options
    bpkg-pkg-unpack.options

The following `pkg-unpack` command options cannot be specified in the default options files:

    --directory|-d
    --purge|-p

# BUGS

Send bug reports to the users@build2.org mailing list.