sync: make `--clean` optional

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

.TH AUR-SYNC 1 2022-03-03 AURUTILS
.SH NAME
aur\-sync \- download and build AUR packages automatically
.
.SH SYNOPSIS
.SY "aur sync"
.OP \-cfknorSu
.IR pkgname ...
.YS
.
.SH DESCRIPTION
.B aur\-sync
downloads and builds AUR packages automatically to a local
repository. It can be seen as a high level composition of
.B aurutils
programs.
.B aur\-sync
performs the following tasks:
.IP \(bu 4
Resolve AUR dependencies with
.BR aur-depends (1)
.IP \(bu 4
Retrieve build files with
.BR aur-fetch (1)
.IP \(bu 4
Present build files before their execution with
.BR aur\-view (1)
.IP \(bu 4
Build the packages with
.BR aur-build (1)
.PP
Package names serve as arguments.
.PP
.B Note:
.B aur\-sync
does not expose all available functionality from
.B aurutils
programs. It serves as an example how these programs can interoperate
for a fully automated AUR workflow.
.
.SH OPTIONS
.TP
.B \-\-continue
Do not download package files.
.
.TP
.BI \-\-ignore= PACKAGE
Ignore a package upgrade. Multiple packages can be specified by
separating them with a comma, or by repeating the \fB\-\-ignore\fR option.
.
.TP
.BI \-\-ignore\-file= FILE
Ignore package upgrades listed in
.IR FILE .
Defaults to
.BR $XDG_CONFIG_HOME/aurutils/sync/ignore .
Targets are placed on single lines and interpreted as
.IR <repository>/<package> .
For example:
.RS
.PP
.EX
custom/package-foo
custom/package-bar
custom-testing/package-baz
.EE
.PP
If the
.I <repository>
prefix is not specified, targets apply to all local repositories.
Comments can be specified after a number sign.
.RE
.
.TP
.BI \-k " NUM" "\fR,\fP \-\-keep\-going=" NUM
Keep going until
.I NUM
packages fail to build
.RB ( "ninja -k" ).
If
.I NUM
is set to
.BR 0 ,
continue indefinitely. On failure, a summary is printed of failed and
succeeded builds. Requires
.B AUR_SYNC_USE_NINJA
(see
.BR ENVIRONMENT ).
.
.TP
.BR \-\-noview ", " \-\-no\-view
Do not present build files for inspection.
.
.TP
.BR \-u ", " \-\-upgrades
Update all obsolete AUR packages in a local repository.
.
.SS Dependency options
Build dependencies are resolved with
.BR aur\-depends (1).
.
.TP
.BR \-\-optdepends
Take
.B optdepends
into account when resolving dependencies.
.RB ( "aur\-depends \-\-optdepends" )
.
.TP
.BR \-\-nocheck ", " \-\-no\-check
Do not handle
.BR checkdepends .
.RB ( "aur\-build \-\-no\-check" ", " "aur\-depends \-\-no\-checkdepends" )
.
.TP
.BR \-\-nograph ", " \-\-no\-graph
Do not verify the AUR dependency graph with
.BR aur\-graph (1).
.
.TP
.BR \-\-nover ", " \-\-no\-ver
Disable version checking for packages.
.
.TP
.BR \-\-nover\-argv ", " \-\-no\-ver\-argv
Disable version checking for packages specified on the command line or
upgrade candidates from
.BR \-\-upgrades .
Version checks for package dependencies remain enabled.
.
.TP
.BR \-\-noprovides ", " \-\-no\-provides
Do not take virtual dependencies
.RB ( provides )
in pacman
.I sync
repositories into account to resolve package dependencies.  Packages
specified on the command-line or available as an upgrade
.RB ( "aur\-sync \-u" ),
are taken as targets regardless of this setting.
.
.TP
.BI \-\-provides\-from= DIR1,...
Only take specified (comma-separated)
.BR pacman (8)
repositories into account when checking virtual dependencies. If the
same package is provided in multiple repositories, ordering is ignored
(for example,
.I \-\-provides\-from=a,b
is equivalent to
.IR \-\-provides\-from=b,a )
and dependencies are installed according to the order defined in
.BR pacman.conf (5).
Packages specified on the command-line or available as an upgrade
.RB ( "aur\-sync \-u" ),
are taken as targets regardless of this setting.
.
.SS Database options
Values for the following options are automatically selected, if a
single local repository is defined in
.BR pacman.conf (5).
See
.BR aur\-repo (1)
for details.
.
.TP
.BI \-d " NAME" "\fR,\fP \-\-database=" NAME
Use the
.I NAME
repository. If this option is not specified,
.B aur\-sync
defaults to the first
.I file://\fR
repository in
.BR pacman.conf (5),
or aborts if multiple are available.
.
.TP
.BI \-\-root= DIR
The location of the repository root. Defaults to the
.I Server
value of the configured repository.
.
.SS Fetch options
If new AUR commits are available,
.B aur\-sync
discards local (non-commited) changes and merges the new commits with
.BR "git\-merge \-\-ff\-only"
by default.
.RB ( "aur\-fetch \-\-discard" )
.PP
If a repository has the
.B aurutils.rebase
.BR git\-config (1)
set to
.IR true ,
discards local changes unconditionally and runs
.BR git\-rebase
in this specific repository.
.RB ( "aur\-fetch \-\-auto" )
.PP
The default behavior can be modified with the options below.
.
.TP
.B \-\-ff
Merge new AUR commits with
.BR "git\-merge \-\-ff"
for all repositories.
.RB ( "aur\-fetch \-\-ff" )
.
.TP
.B \-\-rebase
Merge new AUR commits with
.BR "git\-rebase"
for all repositories.
.
.TP
.B \-\-reset
Discard local changes and commits with
.BR "git\-reset"
for all repositories.
.RB ( "aur\-fetch \-\-reset" )
.
.SS Build options
The default build command is
.BR "aur-build \-\-syncdeps" .
Specifying
.BR aur\-build (1)
options such as
.B \-\-chroot
or
.B \-\-force
to
.B aur\-sync
will append these options to the build command. This section only lists
common options. See
.BR aur\-build (1)
for more information.
.
.TP
.BR \-c ", " \-\-chroot
Build packages in a systemd\-nspawn container.
.RB ( "aur build \-c" )
.
.TP
.BR \-f ", " \-\-force
Continue the build process if a package with the same name exists.
.RB ( "aur build \-f" )
.
.TP 
.BR \-n ", " \-\-noconfirm ", " \-\-no\-confirm
Do not wait for user input when installing or removing build dependencies.
.RB ( "aur build \-n" )
.
.TP
.BR \-o ", " \-\-nobuild ", " \-\-no\-build
Print target packages and their paths instead of building them.
.
.TP
.BR \-C ", " \-\-clean
Clean up leftover work files and directoreis after a successful build.
.RB ( "aur build \-C" )
.
.TP
.BR \-\-cleanbuild
Remove the source directory before building the package.
.RB ( "aur build \-\-cleanbuild" )
.
.TP
.BR \-\-pkgver
Run
.B "makepkg \-od \-\-noprepare"
before the build process.
.RB ( "aur\-build \-\-pkgver" )
.
.TP
.BR \-r ", " \-\-rmdeps ", " \-\-rm\-deps
Remove dependencies installed by makepkg.
.RB ( "aur build \-r" )
.
.TP
.BR \-S ", " \-\-sign ", " \-\-gpg-sign
Sign built packages with
.BR gpg (1).
.RB ( "aur build \-S" )
.
.TP
.B \-\-makepkg\-conf
The
.BR makepkg.conf (5)
file for chroot and
.BR makepkg (8)
operations.
.RB ( "aur\-build \-\-makepkg\-conf" )
.
.TP
.B \-\-pacman\-conf
The
.BR pacman.conf (5)
file for chroot and local repository operations.
.RB ( "aur\-build \-\-pacman\-conf" ", " "aur-repo \-\-config" )
.
.SS View options
.TP
.BI \-\-format= TYPE
If
.I TYPE
is
.B diff
or
.BR log ,
generate diffs with
.BR git\-diff (1)
or
.BR git\-log (1),
respectively.
.RB ( "aur\-view \-\-format" )
.
.TP
.BI \-\-exclude= FILE
Do not include
.I FILE
in the diff output. Can be specified multiple times.
.RB ( "aur\-view \-\-exclude" )
.
.TP
.BI \-\-prefix
Prepend package names in the diff output instead of
.I a/
and
.IR b/ .
.RB ( "aur\-view \-\-prefix" )
.
.SH ENVIRONMENT
Environment variables for other
.B aur
programs are also supported in
.BR aur\-sync .
The below are specific to
.BR aur\-sync .
.TP
.B AURDEST
Determines where build files will be cloned. This must be an absolute path.
Defaults to
.IR $XDG_CACHE_HOME/aurutils/sync .
When persisting local modifications
with
.B \-\-rebase
or
.BR \-\-ff ,
it is advised to set a persistent path such as
.IR /home/aurpkgs .
.
.TP
.B AUR_SYNC_USE_NINJA
When set to a positive value, run
.B aur\-build
command-lines with
.BR ninja .
If a package fails to build, this allows
.B aur\-sync \-\-keep\-going
to continue with remaining, independent packages.
.PP
.RS
The
.IR $AURDEST/ninja-$USER-$$
directory contains the
.B build.ninja
file and timestamps
.IB \fR( \fIpkgbase \fR. stamp \fR)
for each job. It is removed on successful completion of
.BR ninja ,
or if
.B \-\-no\-build
is specified.
.RE
.
.SH NOTES
.SS Standard input
Targets may be taken from stdin using
.BR xargs (1).
For example, to sync all installed packages in a local repository named
.IR custom :
.PP
.EX
    $ paclist custom | awk \(aq{print $1}\(aq | xargs \-r aur sync \-\-noconfirm
.EE
.PP
Note that command output interferes with input from the tty. The
.B \-\-noconfirm
option is used to disable interaction with
.B pacman
when installing dependencies. Alternatively, command or process substitution
can be used:
.PP
.EX
    $ xargs \-a <(paclist custom | awk \(aq{print $1}\(aq) aur sync
    $ aur sync $(paclist custom | awk \(aq{print $1}\(aq)
.EE
.
.SS File retrieval
When version checks are enabled (i.e. \fB\-\-no\-ver\fR is not specified),
build files are only retrieved if the remote (RPC) version is newer
than the version in a pacman database. Checks assume there are no
mismatches between
.B .SRCINFO
and
.B PKGBUILD
files.
.
.SS lib32
Architecture-specific depends (as introduced with pacman 4.2) are
merged with regular depends in RPC queries.
.B aur\-sync
works around this by stripping the
.I lib32\-
prefix from packages and removing
.I gcc\-multilib
if the i686 architecture is detected.
.
.SH SEE ALSO
.ad l
.nh
.BR aur (1),
.BR aur\-build (1),
.BR aur\-depends (1),
.BR aur\-fetch (1),
.BR aur\-graph (1),
.BR aur\-repo (1),
.BR aur\-repo\-filter (1),
.BR aur\-vercmp (1),
.BR aur\-view (1)
.
.SH AUTHORS
.MT https://github.com/AladW
Alad Wenter
.ME
.
.\" vim: set textwidth=72: