aura.8

.\" Man page for `aura`
.\" Written by Colin Woodbury <colingw@gmail.com>

.TH aura 8 "May 2014" "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 can also be used to build Arch Build System (ABS) packages from source.
Aura allows \fIall\fR pacman operations and provides \fInew\fR custom ones
for dealing with AUR and ABS 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\-M\fR, \-\-abssync
.RS 4
Perform actions involving the ABS Tree.
Allows you to [M]anually build repository packages.
.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.
\fI\-O\fR's default action can do one of two things. 
If no extra argument is given, the current orphan packages installed
are displayed. If a package name is given, it is `adopted`.
This changes the package's install reason to `As Explicit`.
This is a shortcut for `-D --asexplicit`.
.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(s)>
.RS 4
Search the AUR via words only (no regex). Results are sorted by vote. 
Suboptions:
.RS 4
\fI\-\-abc\fR  : Sorts results alphabetically.
.P
\fI\-\-head\fR : Only show the first 10 results.
.P
\fI\-\-tail\fR : Only show the last 10 results.
.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\-w\fR, \-\-downloadonly <package(s)>
.RS 4
Download the source tarball. This doesn't contain source code, but instead
the PKGBUILD and .install file for the requested package. Running
\fImakepkg\fR in a directory with these files in it would build the package
manually.
.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\-\-aurignore\fR=<package>(,<package>,...)
.RS 4
Ignore the given packages when installing and upgrading. \fIMust\fR be run
like:
.RS 6
"aura -A foo --aurignore=bar" or "aura -A foo --aurignore=bar,baz,biff"
.RE
.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:
.RS 6
"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\-\-custom\fR
.RS 4
Run \fIcustomizepkg\fR on packages before building. Note that you need
customizepkg installed and set up correctly for this to work.
.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\-\-hotedit\fR
.RS 4
Prompt the user immediately before dependency checks to ask if they
wish to view/edit the PKGBUILD.
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.
.RE
.P
\fB\-\-ignorearch\fR
.RS 4
A \fImakepkg\fR flag visible at the Aura level. Ignores processor architecture
when building packages.
.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
.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

.SH DOWNGRADE OPTIONS (\fI\-C\fR)
.P
\fB\-b\fR, \-\-backup <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.
Pass \fIc\fR twice to 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 ABS TREE OPTIONS (\fI\-M\fR)
.P
\fB\-a\fR, \-\-delmakedeps
.RS 4
The ABS equivalent of \fI\-Aa\fR.
.RE
.P
\fB\-c\fR, \-\-clean
.RS 4
Delete the local ABS Tree.
.RE
.P
\fB\-d\fR, \-\-deps <package(s)>
.RS 4
The ABS equivalent of \fI\-Ad\fR. Will silently fail if the
package is not present in the local tree.
.RE
.P
\fB\-i\fR, \-\-info <package(s)>
.RS 4
Search the local ABS Tree for package info. Will silently fail if the
package is not present in the local tree.
.RE
.P
\fB\-k\fR, \-\-diff
.RS 4
The ABS equivalent of \fI\-Ak\fR.
.RE
.P
\fB\-p\fR, \-\-pkgbuild <package(s)>
.RS 4
The ABS equivalent of \fI\-Ap\fR. Will silently fail if the
package is not present in the local tree.
.RE
.P
\fB\-s\fR, \-\-search <regex>
.RS 4
Search the local ABS Tree via a regex.
.RE
.P
\fB\-t\fR, \-\-treesync <package(s)>
.RS 4
Given package names, syncs them to the local ABS Tree. \fI\-Mt\fR is thus a
more specialised version of \fI\-My\fR.
.RE
.P
\fB\-x\fR, \-\-unsuppress
.RS 4
The ABS equivalent of \fI\-Ax\fR.
.RE
.P
\fB\-y\fR, \-\-refresh
.RS 4
Sync all packages present in the local ABS Tree to their latest version.
This is different from just "sudo abs", which pulls down the \fIentire\fR tree as
available from the repositories.
.RE
.P
\fB\-\-absdeps\fR
.RS 4
All repository (pacman) dependencies not yet installed will also be manually built.
Also usable with \fI\-A\fR.
.RE
\fB\-\-dryrun\fR
.RS 4
Same as with \fI\-A\fR. No building/installation will be performed.
.RE
.P
\fB\-\-hotedit\fR
.RS 4
Same as with \fI\-A\fR. Edit PKGBUILDs before building.
.RE

.SH ORPHAN PACKAGE OPTIONS (\fI\-O\fR)
.P
\fB\-j\fR, \-\-abandon
.RS 4
Uninstall all orphan 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

.SH MISC. OPTIONS
.P
These options do not require a superordinate flag, such as \fI\-A\fR.
.P
\-\-auradebug
.RS 4
Display settings information when running aura.
.RE
.P
\-\-languages
.RS 4
Display the available output languages.
.RE
.P
\-\-no-pp
.RS 4
Don't use powerpill, even if you have it installed.
.RE
.P
\-\-viewconf
.RS 4
View the pacman configuration file in read-only mode.
.RE
.P

.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

.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
.P
5. Using \fIsudo \-E\fR when building will ensure that your local user's
$EDITOR variable will be used, not root's.

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

.SH BUGS
.P
It is not recommended to install non-ABS, non-AUR packages with pacman or
aura. Aura will assume they are AUR packages during a `-Au` 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 <colingw@gmail.com>

.SH CONTRIBUTORS
.P
Kyle Raftogianis
.P
Nicholas Clarke <nicholas.clarke@sanger.ac.uk>
.P
Denis Kasak <denis.kasak@gmail.com>

.SH TRANSLATORS
.P
(   Polish   ) Chris "Kwpolska" Warrick <kwpolska@kwpolska.tk>
.P
(  Croatian  ) Denis Kasak <denis.kasak@gmail.com>
.P
(  Swedish   ) Fredrik Haikarainen
.P
(   German   ) Lukas Niederbremer <Lukas.Niederbremer@HS-Osnabrueck.de>
.P
(  Spanish   ) Alejandro Gómez <alejandroogomez@gmail.com>
.P
( Portuguese ) Henry "Ingvij" Kupty
.P
(   French   ) Ma Jiehong
.P
(   French   ) Fabien Dubosson
.P
(  Russian   ) Kyrylo Silin <kyrylosilin@gmail.com>
.P
(  Italian   ) Bob Valantin
.P
(  Serbian   ) Filip Brcic
.P
( Norwegian  ) "chinatsun"