aura-3.0.0: doc/aura.8

.\" Man page for `aura`
.\" Written by Colin Woodbury <colin@fosskers.ca>

.TH aura 8 "2020 May" "Aura" "Aura Manual"

.\" Disable hyphenation.
.nh

.SH NAME
aura \- A package manager for Arch Linux and the AUR.

.SH SYNOPSIS
\fIaura\fR <operation> [options] [package(s)]

.SH DESCRIPTION
.P
\fIaura\fR is a secure, multilingual package manager for Arch Linux written in
Haskell. It connects to both the official Arch repositories and to the Arch User
Repositories (AUR), allowing easy control of all packages on an Arch system.
Aura allows \fIall\fR pacman operations and provides \fInew\fR custom ones for
dealing with AUR packages.

.SH OPERATIONS
.P
\fB\-A\fR, \-\-aursync [package(s)]
.RS 4
Perform actions involving the [A]UR. Default action installs packages from the
AUR. During building, makepkg output is \fInot\fR shown by default. After
building, the built \fI.pkg.tar.xz\fR file is moved to the package cache and
installed from there. This allows for easy AUR package downgrading.
.RE
.P
\fB\-B\fR, \-\-save
.RS 4
Manage the saving and restoring of the global package state. Default action
stores a record of all currently installed packages and their versions.
.RE
.P
\fB\-C\fR, \-\-downgrade [package(s)]
.RS 4
Perform actions involving the package [C]ache. Default action downgrades
specified packages. This process is interactive, allowing the user to choose
from any previous version they have available in the package cache.
.RE
.P
\fB\-L\fR, \-\-viewlog
.RS 4
Perform actions involving the pacman [L]ogfile.
Default action opens the log for read-only viewing.
.RE
.P
\fB\-O\fR, \-\-orphans [package(s)]
.RS 4
Perform actions involving [O]rphan packages. Orphan packages are packages
installed as dependencies, but are no longer required by any other package.
Default action is to list the current orphans.
.RE
.P
\fB\-P\fR, \-\-analysis <stdin>
.RS 4
Perform security analysis of a [P]KGBUILD. Useful for package maintainers and
sysadmins to verify the safety of the PKGBUILD files that they write. To test
any package on the AUR, try the following:
.P
.RS 4
aura -Ap <package> | aura -P
.RE

.SH AUR SYNC OPTIONS (\fI\-A\fR)
.P
\fB\-a\fR, \-\-delmakedeps
.RS 4
Uninstalls build dependencies that are no longer required after installing the
main package. This prevents the creation of orphan packages. Also note that
while the package itself will be uninstalled, its package file will remain in
the cache.
.RE
.P
\fB\-d\fR, \-\-deps <package(s)>
.RS 4
View all the dependencies of a package. This process is recursive for AUR
packages, so all dependencies of dependencies (and so on) will also be shown.
This can aid the pre-install package research process.
.RE
.P
\fB\-i\fR, \-\-info <package(s)>
.RS 4
View information about a package in the AUR.
.RE
.P
\fB\-k\fR, \-\-diff
.RS 4
Shows PKGBUILD diffs. When upgrading, using this option will compare the most
and second-most recent PKGBUILDs and output changes in colour.
.RE
.P
\fB\-p\fR, \-\-pkgbuild <package(s)>
.RS 4
Outputs an AUR package's PKGBUILD. Use this before installing new packages to
confirm that the build scripts aren't doing anything fishy.
.RE
.P
\fB\-q\fR, \-\-quiet
.RS 4
Display less information about certain aursync operations (this is useful when
processing Aura's output in a script). In particular, search and view
dependencies will only show uncoloured package names.
.RE
.P
\fB\-s\fR, \-\-search <word>
.RS 4
Search the AUR via a word only (no regex). Results are sorted by vote.
Suboptions:
.RS 4
\fI\-\-abc\fR    : Sorts results alphabetically.
.P
\fI\-\-head\=n\fR : Only show the first n results. Default n = 10
.P
\fI\-\-tail\=n\fR : Only show the last n results.  Default n = 10
.RE
.RE
.P
\fB\-u\fR, \-\-sysupgrade
.RS 4
Upgrade all installed AUR packages. \fI\-Au\fR is \fI\-Su\fR for AUR packages.
.RE
.P
\fB\-x\fR, \-\-unsuppress
.RS 4
Unsuppress \fImakepkg\fR output during building. By default this output is
suppressed for a more silent install. Note that when this option isn't used,
\fImakepkg\fR output is actually collected and printed if any errors occur.
.RE
.P
\fB\-\-json <package(s)>
.RS 4
Query the AUR RPC for package info as raw JSON. Good for debugging.
.RE
.P
\fB\-\-build\fR <path>
.RS 4
Specify build path when building AUR packages. Only the \fIfull\fR path of a
pre-existing directory can be used. Example:
.P
.RS 4
aura -A foo --build=/full/path/to/build/location/
.RE
.RE
.P
\fB\-\-builduser\fR <username>
.RS 4
Specify the user to build packages as. This can be useful when logged in as
root and a build user is available.
.RE
.P
\fB\-\-devel\fR
.RS 4
When ran with \fI\-Au\fR, adds all development packages to the queue of
packages to upgrade. Devel packages are those pulled directly from online
repositories, via git / mercurial / etc.
.RE
.P
\fB\-\-dryrun\fR
.RS 4
When ran with \fI\-A\fR or \fI\-Au\fR, update checks, PKGBUILD diffs, and
dependency checks will be performed, but nothing will be built. Also usable
with \fI\-M\fR.
.RE
.P
\fB\-\-force\fR
.RS 4
Always (re)build the specified packages. Usually Aura will not rebuild packages
whose versions are already available in the local package cache.
.RE
.P
\fB\-\-hotedit\fR
.RS 4
Prompt the user before building to ask if they wish to view/edit the PKGBUILD,
as well as any .install or .patch files. This is not default behavior and thus
does not have a single\-letter option. Research into packages (and by extension,
their PKGBUILDs) should be done before any building occurs. Please use
\fI\-Ap\fR and \fI\-Ad\fR for this, as they will be much faster at presenting
information than searching the AUR website manually. Note that, since aura is
run through sudo, your local value of $EDITOR may not be preserved. Run as "sudo
\fI\-E\fR aura -A --hotedit ..." to preserve your environment. To always allow
environment variables to be passed, have a look at the \fIenv_reset\fR and
\fIenv_keep\fR options in \fBsudoers\fR(5).
.RE
.P
\fB\-\-vcspath <path>\fR
.RS 4
Save the cloned sources of VCS packages (i.e. those that end in \fI*-git\fR, etc.)
in the given location, instead of the default \fI/var/cache/aura/vcs/\fR.
.RE

.SH GLOBAL PACKAGE STATE OPTIONS (\fI\-B\fR)
.P
\fB\-c\fR, \-\-clean <states-to-retain>
.RS 4
Saves a given number of the most recently saved package states and removes the
rest.
.RE
.P
\fB\-r\fR, \-\-restore\fR
.RS 4
Restores a record kept with \fI\-B\fR. Attempts to downgrade any packages that
were upgraded since the chosen save. Will remove any that weren't installed at
the time.
.RE
.P
\fB\-l\fR, \-\-list\fR
.RS 4
Show all saved package state filenames.
.RE

.SH DOWNGRADE OPTIONS (\fI\-C\fR)
.P
\fB\-b\fR, \-\-backup\fR <path>
.RS 4
Backup the package cache to a given directory. The given directory must already
exist. During copying, progress will be shown. If the copy takes too long, you
may want to reduce the number of older versions of each package by using
\fI\-Cc\fR.
.RE
.P
\fB\-c\fR, \-\-clean <versions-to-retain>
.RS 4
Saves a given number of package versions for each package and deletes the rest
from the package cache. Count is made from the most recent version, so using:
.RS 4
aura -Cc 3
.RE
would save the three most recent versions of each package file.
Giving the number 0 as an argument is identical to \fI\-Scc\fR.
.RE
.P
\fB\-\-notsaved
.RS 4
Remove only those package files which are not saved in a package record (a la \fI\-B\fR).
.RE
.P
\fB\-s\fR, \-\-search <regex>
.RS 4
Search the package cache via a regex. Any package name that matches the regex
will be output as\-is.
.RE

.SH LOGFILE OPTIONS (\fI\-L\fR)
.P
\fB\-i\fR, \-\-info <package(s)>
.RS 4
Displays install / upgrade history for a given package. Under the `Recent
Actions` section, only the last five entries will be displayed. If there are
less than five actions ever performed with the package, what is available will
be printed.
.RE
.P
\fB\-s\fR, \-\-search <regex>
.RS 4
Search the pacman log file via a regex. Useful for singling out any and all
actions performed on a package.
.RE

.SH ORPHAN PACKAGE OPTIONS (\fI\-O\fR)
.P
\fB\-a\fR, \-\-adopt <package(s)>
.RS 4
Mark a package as being explicitly installed (i.e. it's not a dependency).
.RE
.P
\fB\-j\fR, \-\-abandon
.RS 4
Uninstall all orphan packages.
.RE
.SH ANALYSIS OPTIONS (\fI\-P\fR)
.P
\fB\-f\fR, \-\-file <path>
.RS 4
Analyse a given PKGBUILD.
.RE
\fB\-d\fR, \-\-dir <path>
.RS 4
Analyse a PKGBUILD found in the specified directory.
.RE
.P
\fB\-a\fR, \-\-audit
.RS 4
Analyse the PKGBUILDs of all locally installed AUR packages.
.RE

.SH PACMAN / AURA DUAL FUNCTIONALITY OPTIONS
.P
\-\-noconfirm
.RS 4
Never ask for any Aura or Pacman confirmation. Any time a prompt would
appear, say before building or installation, it is assumed the user
answered in whatever way would progress the program.
.RE
.P
\-\-needed
.RS 4
Don't rebuild/reinstall packages that are already up to date.
.RE
.P
\-\-debug
.RS 4
View some handy debugging information.
.RE
.P
\-\-color [mode]
.RS 4
Whether or not to colour output text. Without this flag, both Aura and Pacman
will attempt to colour text if the terminal allows it. Otherwise, you can pass
\fInever\fR or \fIalways\fR to be specific about your wants.
.RE
.P
\-\-overwrite <glob>
.RS 4
If there are file conflicts during installation, overwrite conflicting files
that match the given glob pattern.
.RE

.SH EXPOSED MAKEPKG OPTIONS
.P
\-\-ignorearch
.RS 4
Ignores processor architecture when building packages.
.RE
.P
\-\-allsource
.RS 4
Creates a \fI.src\fR file containing all the downloaded sources (code, etc) and
stores it at \fI/var/cache/aura/src/\fR. To change the location where sources
are stored, use the \fI\-\-allsourcepath\fR flag.
.RE
.P
\-\-skipinteg
.RS 4
Skip package source integrity checks.
.RE

.SH LANGUAGE OPTIONS
.P
Aura is available in multiple languages. As options, they can be used with
either their English names or their real names written in their native
characters. The available languages are, in option form:
.P
\-\-english (default)
.P
\-\-japanese, \-\-日本語
.P
\-\-polish, \-\-polski
.P
\-\-croatian, \-\-hrvatski
.P
\-\-swedish, \-\-svenska
.P
\-\-german, \-\-deutsch
.P
\-\-spanish, \-\-español
.P
\-\-portuguese, \-\-português
.P
\-\-french, \-\-français
.P
\-\-russian, \-\-русский
.P
\-\-italian, \-\-italiano
.P
\-\-serbian, \-\-српски
.P
\-\-norwegian, \-\-norsk
.P
\-\-indonesian
.P
\-\-chinese, \-\-中文
.P
\-\-esperanto
.P
\-\-dutch, \-\-nederlands

.SH PRO TIPS
.P
1. If you build a package and then choose not to install it, the built package
file will still be moved to the cache. You can then install it whenever you
want with \fI\-C\fR.
.P
2. Research packages using \fI\-Ad\fR, \fI\-Ai\fR, and \fI\-Ap\fR!
.P
3. When upgrading, use \fI\-Akua\fR instead of just \fI\-Au\fR.  This will
remove make deps, as well as show PKGBUILD diffs before building.
.P
4. If you want to search both the Repos and the AUR at the same time, you can
use the following shell functions:
.RS 4
Bash => function search() {
          aura -Ss $1 && aura -As $1
        }

Fish => function search
          aura -Ss $argv
          aura -As $argv
        end
.RE

.SH SEE ALSO
.P
\fBpacman\fR(8), \fBpacman.conf\fR(5), \fBmakepkg\fR(8)

.SH BUGS
.P
It is not recommended to install non-AUR packages with pacman or aura. Aura will
assume they are AUR packages during a \fI\-Au\fR and attempt to upgrade them. If
a name collision occurs (that is, if there is a legitimate AUR package with the
same name as the one you installed) previous installations could be overwritten.

.SH AUTHOR
.P
Colin Woodbury <colin@fosskers.ca>

.SH CONTRIBUTORS
.P
Chris Warrick
.P
Brayden Banks
.P
Denis Kasak
.P
Edwin Marshall
.P
Jimmy Brisson
.P
Kyle Raftogianis
.P
Nicholas Clarke

.SH TRANSLATORS
.P
(   Polish   ) Chris Warrick
.P
(  Croatian  ) Denis Kasak and "stranac"
.P
(  Swedish   ) Fredrik Haikarainen and Daniel Beecham
.P
(   German   ) Lukas Niederbremer
.P
(  Spanish   ) Alejandro Gómez, Sergio Conde, and Max Ferrer
.P
( Portuguese ) Henry Kupty, Thiago Perrotta, and Wagner Amaral
.P
(   French   ) Ma Jiehong and Fabien Dubosson
.P
(  Russian   ) Kyrylo Silin and Alexey Kotlyarov
.P
(  Italian   ) Bob Valantin and Cristian Tentella
.P
(  Serbian   ) Filip Brcic
.P
( Norwegian  ) "chinatsun"
.P
( Indonesian ) "pak tua Greg"
.P
( Chinese    ) Kai Zhang
.P
( Japanese   ) Onoue Takuro
.P
( Esperanto  ) Zachary Matthews
.P
(   Dutch    ) Joris Blanken