.\" Process this file with
.\" groff -man -Tascii bpkg-pkg-fetch.1
.\"
.TH bpkg-pkg-fetch 1 "June 2024" "bpkg 0.17.0"
.SH NAME
\fBbpkg-pkg-fetch\fR \- fetch package archive
.SH "SYNOPSIS"
.PP
\fBbpkg pkg-fetch\fR [\fIoptions\fR] (\fIpkg\fR\fB/\fR\fIver\fR |
\fB--existing|-e\fR \fIfile\fR)\fR
.SH "DESCRIPTION"
.PP
The \fBpkg-fetch\fR command fetches the archive for the specified package name
and version from one of the archive-based repositories
(\fBbpkg-rep-add(1)\fP)\. The resulting package state is \fBfetched\fR
(\fBbpkg-pkg-status(1)\fP)\.
.PP
If the \fB--replace|-r\fR option is specified, then \fBpkg-fetch\fR will
replace the archive of a package that is already in the \fBfetched\fR or
\fBunpacked\fR state\. Otherwise, \fBpkg-fetch\fR expects the package to not
exist in the configuration\.
.PP
If the \fB--existing|-e\fR option is used, then instead of the name and
version arguments, \fBpkg-fetch\fR expects a local path to an existing package
archive\. In this case, \fBbpkg\fR will use the archive in place, without
copying it into the configuration directory\. Also, unless the
\fB--purge|-p\fR option is specified, \fBbpkg\fR will not attempt to remove
this archive when the package is later purged with the \fBbpkg-pkg-purge(1)\fP
command\.
.SH "PKG-FETCH OPTIONS"
.IP "\fB--replace\fR|\fB-r\fR"
Replace the archive if the package is already fetched or unpacked\.
.IP "\fB--existing\fR|\fB-e\fR"
Treat the argument as an existing package archive path rather than the package
name/version to fetch\.
.IP "\fB--purge\fR|\fB-p\fR"
Remove the existing package archive when the package is purged\.
.IP "\fB--directory\fR|\fB-d\fR \fIdir\fR"
Assume configuration is in \fIdir\fR rather than in the current working
directory\.
.SH "COMMON OPTIONS"
.PP
The common options are summarized below with a more detailed description
available in \fBbpkg-common-options(1)\fP\.
.IP "\fB-v\fR"
Print essential underlying commands being executed\.
.IP "\fB-V\fR"
Print all underlying commands being executed\.
.IP "\fB--quiet\fR|\fB-q\fR"
Run quietly, only printing error messages\.
.IP "\fB--verbose\fR \fIlevel\fR"
Set the diagnostics verbosity to \fIlevel\fR between 0 and 6\.
.IP "\fB--stdout-format\fR \fIformat\fR"
Representation format to use for printing to \fBstdout\fR\.
.IP "\fB--jobs\fR|\fB-j\fR \fInum\fR"
Number of jobs to perform in parallel\.
.IP "\fB--no-result\fR"
Don't print informational messages about the outcome of performing a command
or some of its parts\.
.IP "\fB--structured-result\fR \fIfmt\fR"
Write the result of performing a command in a structured form\.
.IP "\fB--progress\fR"
Display progress indicators for long-lasting operations, such as network
transfers, building, etc\.
.IP "\fB--no-progress\fR"
Suppress progress indicators for long-lasting operations, such as network
transfers, building, etc\.
.IP "\fB--diag-color\fR"
Use color in diagnostics\.
.IP "\fB--no-diag-color\fR"
Don't use color in diagnostics\.
.IP "\fB--build\fR \fIpath\fR"
The build program to be used to build packages\.
.IP "\fB--build-option\fR \fIopt\fR"
Additional option to be passed to the build program\.
.IP "\fB--fetch\fR \fIpath\fR"
The fetch program to be used to download resources\.
.IP "\fB--fetch-option\fR \fIopt\fR"
Additional option to be passed to the fetch program\.
.IP "\fB--fetch-timeout\fR \fIsec\fR"
The fetch and fetch-like (for example, \fBgit\fR) program timeout\.
.IP "\fB--pkg-proxy\fR \fIurl\fR"
HTTP proxy server to use when fetching package manifests and archives from
remote \fBpkg\fR repositories\.
.IP "\fB--git\fR \fIpath\fR"
The git program to be used to fetch git repositories\.
.IP "\fB--git-option\fR \fIopt\fR"
Additional common option to be passed to the git program\.
.IP "\fB--sha256\fR \fIpath\fR"
The sha256 program to be used to calculate SHA256 sums\.
.IP "\fB--sha256-option\fR \fIopt\fR"
Additional option to be passed to the sha256 program\.
.IP "\fB--tar\fR \fIpath\fR"
The tar program to be used to extract package archives\.
.IP "\fB--tar-option\fR \fIopt\fR"
Additional option to be passed to the tar program\.
.IP "\fB--openssl\fR \fIpath\fR"
The openssl program to be used for crypto operations\.
.IP "\fB--openssl-option\fR \fIopt\fR"
Additional option to be passed to the openssl program\.
.IP "\fB--auth\fR \fItype\fR"
Types of repositories to authenticate\.
.IP "\fB--trust\fR \fIfingerprint\fR"
Trust repository certificate with a SHA256 \fIfingerprint\fR\.
.IP "\fB--trust-yes\fR"
Assume the answer to all authentication prompts is \fByes\fR\.
.IP "\fB--trust-no\fR"
Assume the answer to all authentication prompts is \fBno\fR\.
.IP "\fB--git-capabilities\fR \fIup\fR=\fIpc\fR"
Protocol capabilities (\fIpc\fR) for a \fBgit\fR repository URL prefix
(\fIup\fR)\.
.IP "\fB--pager\fR \fIpath\fR"
The pager program to be used to show long text\.
.IP "\fB--pager-option\fR \fIopt\fR"
Additional option to be passed to the pager program\.
.IP "\fB--options-file\fR \fIfile\fR"
Read additional options from \fIfile\fR\.
.IP "\fB--default-options\fR \fIdir\fR"
The directory to load additional default options files from\.
.IP "\fB--no-default-options\fR"
Don't load default options files\.
.IP "\fB--keep-tmp\fR"
Don't remove the \fBbpkg\fR's temporary directory at the end of the command
execution and print its path at the verbosity level 2 or higher\.
.SH "DEFAULT OPTIONS FILES"
.PP
See \fBbpkg-default-options-files(1)\fP for an overview of the default options
files\. For the \fBpkg-fetch\fR 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:
.PP
.nf
bpkg\.options
bpkg-pkg-fetch\.options
.fi
.PP
The following \fBpkg-fetch\fR command options cannot be specified in the
default options files:
.PP
.nf
--directory|-d
--purge|-p
.fi
.SH BUGS
Send bug reports to the users@build2.org mailing list.
.SH COPYRIGHT
Copyright (c) 2014-2024 the build2 authors.

Permission is granted to copy, distribute and/or modify this document under
the terms of the MIT License.