build: add error if `chroot --status` fails (#1151)

[aurutils.git] / man1 / aur-fetch.1

.TH AUR-FETCH 1 2022-08-04 AURUTILS
.SH NAME
aur\-fetch \- download packages from the AUR
.
.SH SYNOPSIS
.SY "aur fetch [-S] [-f] [--rebase] [--reset]"
.IR pkgbase " [" pkgbase... ]
.YS
.
.SH DESCRIPTION
.B aur\-fetch
downloads packages specified on the command-line from the AUR using
.BR git (1).
If the first argument is
.B \-
or
.BR /dev/stdin ,
packages are taken from standard input.
.PP
.
.BR git (1)
repositories are retrieved with
.BR git\-clone (1)
if they do not exist. Otherwise, the
.B origin
remote is updated with
.BR git\-fetch (1).
Changes can be merged with
.BR git\-merge " (" \-\-merge ),
.BR git\-rebase " (" \-\-rebase ),
or
.BR git\-reset " (" \-\-reset ).
.PP
.B Note:
AUR packages have
.B master
as the only remote branch, so changes are always merged
from
.BR origin/master .
Local changes may however live in different branches.
.
.SH OPTIONS
.TP
.BR \-\-sync=merge ", " \-\-merge
Run
.BR git\-fetch (1)
and merge upstream changes with
.BR git\-merge (1).
.IP
If no
.BR git\-merge (1)
options are specified,
only fast-forwards are allowed with
.BR "git\-merge \-\-ff\-only" .
When specified,
.B aur\-fetch
forwards the
.BR \-\-ff ,
.BR \-\-ff\-only ,
.BR \-\-no\-commit
and
.BR \-\-no\-ff
options to
.BR git\-merge .
.IP
.B Note:
When previewing changes with
.B \-\-no\-commit
it is advised to also use
.BR \-\-no\-ff ,
so that no commits are applied to the index even when a fast-forward is possible. See
.BR git\-merge (1)
for details.
.
.TP
.BR \-\-sync=rebase ", " \-\-rebase
Run
.BR git\-rebase (1)
instead of
.BR git\-merge (1),
re-applying local commits on top of upstream AUR commits. The
.B \-\-no\-ff
option is supported and forwarded to
.BR git\-merge
when specified.
.IP
.B Warning:
If a rebase does not apply cleanly, the user is expected to fix any
issues occurring in the git repository before continuing. A rebase may
also inadvertently keep malicious commits that Trusted Users have
removed from the git history. The
.B \-\-rebase
option should thus be used with care. See
.BR git\-rebase (1)
for details.
.
.TP
.BR \-\-sync=auto ", " \-\-auto
Run
.BR git\-rebase (1)
for a repository with
.B aurutils.rebase
set to
.B true
in
.BR git\-config (1),
and
.BR git\-merge (1)
otherwise.
.
.TP
.BR \-\-sync=reset ", " \-\-reset
Retrieve new revisions with
.B git\-fetch origin
and
.B git\-reset
to the
.B master@{upstream}
commit, removing any local commits.
.
.TP
.BR \-\-discard
When using
.BR \-\-sync=merge
or
.BR \-\-sync=rebase ,
uncommitted changes may cause the operation to fail. Furthermore,
.B git\-rebase
expects a clean work tree.
.IP
With
.BR \-\-sync=merge ,
the
.B \-\-discard
option checks if new upstream commits are available with
.BR git\-merge\-base .
If so, uncommited changes are discarded with
.BR git\-checkout .
.IP
With
.BR \-\-sync=rebase ,
the
.B \-\-discard
option runs
.BR git\-checkout
unconditionally.
.
.TP
.BR \-\-existing
Check if a git repositories exist in AUR using
.BR git\-ls-remote (1)
before retrieving or updating them.
.
.TP
.BR \-r ", " \-\-recurse
Download packages and their dependencies with
.BR aur\-depends (1).
If this option is specified, arguments must be supplied by
.B pkgname
instead of by
.BR pkgbase .
.
.TP
.BI \-\-results= FILE
Write colon-delimited output in the following form to
.IR FILE :
.IP
.I <action>:<head_from>:<head_to>:file://<path>
.IP
Possible values for
.I <action>
are
.BR clone ,
.BR merge ,
.BR rebase ,
and
.BR fetch .
Can be used by higher level tools to differentiate new clones from
updates to existing repositories.
.IP
If
.I action
is set to
.BR clone ,
.I <head_from>
is set to
.BR 4b825dc642cb6eb9a060e54bf8d69288fbee4904 ,
the
.BR git (1)
empty tree object.
.I <path>
is the absolute path to the corresponding git repository.
.IP
.B Note:
When using
.B \-\-no\-commit \-\-no\-ff
and
.BR git\-merge(1) ,
.I <head_from>
and
.I <head_to>
will be identical.
.
.SH ENVIRONMENT
.TP
.B AUR_LOCATION
URI where repositories are cloned from. Defaults to
.MT https://aur.archlinux.org .
.ME .
.
.TP
.B AUR_MIRROR
URI to an AUR mirror, a
.BR git (1)
repository where each package is contained in a
.BR git\-branch (1).
Defaults to
.MT https://github.com/archlinux/aur
.ME .
.
.TP
.B AUR_MIRROR_TTL
When updating an AUR mirror, a list of all branches is retrieved with
.BR git\-ls\-remote
to validate arguments. The
.B AUR_MIRROR_TTL
variable defines (in seconds) how often this command is run. For accurate
results, this should roughly equal the synchronization interval between AUR and
its mirrors. Defaults to
.IR 300 .
.
.TP
.B AUR_MIRROR_BRANCH
The default branch of an AUR mirror. Defaults to
.BR main .
.
.TP
.B AUR_FETCH_USE_MIRROR
If this variable is set to a positive value, clone repositories from an AUR
mirror instead of
.BR AUR_LOCATION .
Upstream changes are merged from
.I origin/<package>
instead of
.IR origin/master .
.IP
Remotes of existing
.BR git (1)
repositories are preserved. When enabling or disabling
.BR AUR_FETCH_MIRROR ,
repositories should be converted manually with
.B git\-remote set\-url
and
.BR "git\-remote set\-branches origin" .
.
.TP
.B AUR_ROOT
Directory where an AUR mirror is cloned to. Defaults to
.IR XDG_CACHE_HOME/aur .
.
.SH SEE ALSO
.ad l
.nh
.BR aur (1),
.BR aur\-depends (1),
.BR git (1),
.BR git\-clone (1),
.BR git\-config (1),
.BR git\-fetch (1),
.BR git\-merge (1),
.BR git\-pull (1),
.BR git\-rebase (1),
.BR git\-reset (1),
.BR git\-rev\-parse (1)
.
.SH AUTHORS
.MT https://github.com/AladW
Alad Wenter
.ME
.
.\" vim: set textwidth=72: