# NAME

`bpkg-pkg-checkout` – check out package version

# SYNOPSIS

`bpkg pkg-checkout [options] pkg/ver`

# DESCRIPTION

The `pkg-checkout` command checks out the specified package version from one of the version control-based repositories (`bpkg-rep-add(1)`). The resulting package state is `unpacked` (`bpkg-pkg-status(1)`).

If the `--output-root` option is passed, then the package is checked out into the specified directory rather than into the configuration directory. In this case, `bpkg` uses the package (source) directory in place, similar to the `pkg-unpack --existing|-e` mode. Also, unless the `--output-purge` option is specified, `bpkg` will not attempt to remove this directory when the package is later purged with the `bpkg-pkg-purge(1)` command. Note also that such a package is not external (see `bpkg-pkg-unpack(1)` for details).

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

# PKG-CHECKOUT OPTIONS

`--replace`|`-r`
  Replace the source directory if the package is already fetched or unpacked.
`--output-root` `dir`
  Check out the package into the specified directory rather than into the configuration directory. Note that the package source is placed into the `package-version` subdirectory of this directory.
`--output-purge`
  Remove the checked out package (source) directory when the package is purged.
`--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-checkout` 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-checkout.options

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

    --directory|-d

# BUGS

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