AUR(1)

NAME
aur - helper tool for the arch user repository

DESCRIPTION
aur(1) is the command wrapper for aurutils, a collection of scripts to automate usage of the Arch User Repository. Different tasks such as update checks, package searching, and computing dependencies are split to separate commands.

The chosen approach for managing packages is local pacman repositories, instead of foreign (installed by pacman -U) packages.

A brief overview of local repositories is given in the CREATING A LOCAL REPOSITORY section.

AUR COMMANDS
The below gives a short overview; see the respective documentation for details.

aur(1) searches for commands in /usr/lib/aurutils/ by default, followed by $PATH as set in the environment. A different path may be set at run-time through the AUR_EXEC_PATH environment variable, for example /usr/local/lib/aurutils:/usr/lib/aurutils.

aur-build(1)
    Build packages to a local repository.

aur-chroot(1)
    Build pacman packages with systemd-nspawn.

aur-depends(1)
    Retrieve dependencies using aurweb.

aur-fetch(1)
    Fetch packages from a location.

aur-graph(1)
    Print package/dependency directed graph.

aur-pkglist(1)
    Print the AUR package list.

aur-query(1)
    Send GET requests to the aurweb RPC interface.

aur-repo(1)
    Manage local repositories.

aur-repo-filter(1)
    Filter packages in the Arch Linux repositories.

aur-search(1)
    Search for AUR packages.

aur-srcver(1)
    List version of VCS packages.

aur-sync(1)
    Download and build AUR packages automatically.

aur-vercmp(1)
    Check packages for AUR updates.

aur-view(1)
    Inspect git(1) repositories.

EXIT STATUS
Programs follow a subset of errno(3), or preserve command status where applicable.

ENVIRONMENT
Environment variables for aur programs are prefixed with AUR. Where applicable, standard variables such as XDG_CONFIG_HOME are respected. Variables supported by specific programs are listed in their respective man pages (see AUR COMMANDS).

Variables can be set in the user environment or in $XDG_CONFIG_HOME/aurutils/env, using a key/value format separated by newlines. For example:

        AURDEST=/home/custompkgs
        AUR_PACMAN_AUTH=sudo --askpass
        AUR_PAGER=ranger
        AUR_REPO=custom

AUR_DEBUG
    Setting this variable enables debug mode (typically xtrace for bash(1) scripts) in aur programs.

AUR_EXEC_PATH
    The path in which aur searches for commands, prepended to $PATH. Defaults to /usr/lib/aurutils.

NO_COLOR
    Output colorization can be disabled by setting this environment variable.

CREATING A LOCAL REPOSITORY
A local repository may be configured directly in /etc/pacman.conf, or in a separate file specified with the Include directive. This section documents an example configuration; for details, consult the pacman.conf(5) man page.

Note:
    Avoid naming the repository local, as this name is reserved by pacman(8).

Tip:
    Consider separate repositories for different purposes, such as version control packages.

  Pacman configuration
For the purposes of this example, we assume the local repository custom is located in /home/custompkgs.

Append a section for the local repository to /etc/pacman.conf

        [custom]
        SigLevel = Optional TrustAll
        Server = file:///home/custompkgs

Create the repository root and database:

        $ sudo install -d /home/custompkgs -o $USER
        $ repo-add /home/custompkgs/custom.db.tar.gz

If built packages are available, add them to the database:

        $ cd /home/custompkgs
        $ repo-add -n custom.db.tar.gz *.pkg.tar*

Synchronize pacman:

        $ sudo pacman -Syu

  CacheDir (optional)
When packages from a local repository are installed through pacman -S, they are copied to a cache directory (usually /var/cache/pacman/pkg) by pacman. Besides using additional space, this may result in checksum mismatches when rebuilding packages without increasing pkgrel. (See GitHub issue #85)

To avoid this, set the repository path as a pacman CacheDir, together with the CleanMethod = KeepCurrent setting to avoid unexpected deletion of built packages with pacman -Sc.

This can be done by editing /etc/pacman.conf as follows:

        [options]
        CacheDir = /var/cache/pacman/pkg /home/custompkgs
        CleanMethod = KeepCurrent

In addition, SigLevel should be set to Never or Always, if package signing is disabled or enabled, respectively. This avoids pacman copying over packages to the main CacheDir, if signature files are missing and SigLevel = Optional is set. (FS#71109)

Note that pacman -Scc will remove packages regardless of the CleanMethod setting.

EXAMPLES
In this section, we assume that bash(1) is the interactive shell.

  Arch User Repository
Run actions on the dependency tree of an AUR package:

        $ aur depends foo | while read -r pkg; do ... done

Retrieve AUR packages and their dependencies recursively:

        $ aur depends --pkgbase foo | aur fetch -

Retrieve all AUR packages from a given maintainer:

        $ aur search -m mcaur --table | cut -f2 | uniq -u | aur fetch -

Build plasma-desktop-git and its dependencies with systemd-nspawn(1):

        $ aur sync -c plasma-desktop-git

Update all AUR packages in a single local repository:

        $ aur sync -u

Check foreign packages for AUR updates:

        $ pacman -Qm | aur vercmp

Check the custom repository for AUR updates:

        $ aur repo -d custom --list | aur vercmp

If pacman.conf only contains one local repository, the above may be shortened to:

        $ aur repo --upgrades

  Arch User Repository - advanced usage
Print packages from the custom repository that are unavailable in the AUR:

        $ grep -Fxvf <(aur pkglist) <(pacman -Slq custom)

As above, but for orphaned packages:

        $ pacman -Slq custom | aur query -t info - | \
              jq -r '.[].results[] | select(.Maintainer == null)'

Update packages in the custom repository which are installed on the host:

        $ grep -Fxf <(pacman -Qq) <(pacman -Slq custom) > installed.txt
        $ xargs -a installed.txt aur sync -d custom

Search for AUR packages with both wm and git in the name:

        $ aur pkglist -P '(?=.*wm)(?=.*git)' | aur search -i -

Select an AUR package with name matching pony, and build the result:

        $ select a in $(aur pkglist -F pony); do aur sync "$a"; break; done

  Official repositories
Print Perl modules that are both in the AUR and official repositories:

        $ aur pkglist -P '^perl-.+' > perl.txt
        $ grep -Fxf <(aur repo-filter < perl.txt) perl.txt

Print packages both in AUR and [community] and compare their versions:

        $ aur repo -d community --all

  Using PKGBUILDs
Build packages in the pkgbuilds github repository (generating required .SRCINFO files):

        $ git clone https://www.github.com/Earnestly/pkgbuilds
        $ cd pkgbuilds
        $ find -name PKGBUILD -execdir sh -c 'makepkg --printsrcinfo > .SRCINFO' \;
        $ aur graph */.SRCINFO | tsort | tac > queue # Remove unwanted targets
        $ aur build -a queue

Build a package for a different architecture, here i686:

        $ setarch i686 aur sync -c --repo=custom_i686 tclkit

  Custom commands
The following scripts are examples of custom commands added anywhere in $PATH, for example /usr/local/bin.

aur-gc

        #!/bin/bash
        # Remove unused build files in aur-sync cache
        XDG_CACHE_HOME=${XDG_CACHE_HOME:-$HOME/.cache}
        AURDEST=${AURDEST:-$XDG_CACHE_HOME/aurutils/sync}
        # Assumes build files were retrieved through git(1)
        find "$AURDEST" -name .git -execdir git clean -xf \;
        # Print directories which do not contain a PKGBUILD file
        for d in "$AURDEST"/*; do
            [[ -f $d/PKGBUILD ]] || printf '%s\n' "$d"
        done

aur-remove

        #!/bin/sh --
        # aur-remove - remove listed packages from all local repositories
        if [ "$#" -eq 0 ]; then
            printf 'usage: aur remove package [package ...]\n' >&2
            exit 1
        fi
        aur repo --list-path | while read -r repo_path; do
            repo-remove "$repo_path" "$@"
            paccache -c "${repo_path%/*}" -rvk0 "$@"
        done

  Using third-party helpers
Repository packages can be "made foreign" by temporarily removing the repository from the pacman configuration. This can be used with programs that support the PACMAN environment variable and check foreign packages for AUR updates.

For example, create the mypacman script in /usr/local/bin/mypacman:

        #!/bin/sh
        pacman --config=/usr/share/devtools/pacman-extra.conf "$@"

and point the PACMAN variable towards it:

        $ export PACMAN=/usr/local/bin/mypacman

AUTHORS
Alad Wenter (https://github.com/AladW)