# aurutils, an AUR helper built around local pacman repositories > aurutils is a collection of shell scripts for the Arch User Repository that deliberately avoids pacman -U foreign packages and manages AUR content through local pacman repositories instead. The build is a small Makefile over a shell library, and the documentation lives in man pages. **aurutils/aurutils** — Helper tools for the AUR. - Repository: https://github.com/aurutils/aurutils - Stars: 1,063 · Forks: 94 - Language: Shell - License: ISC - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/aurutils-aurutils ## Foreign packages are the thing it tries to avoid The README states the approach in one line, and it is the design decision that defines the project: the chosen approach for managing packages is local pacman repositories, rather than foreign packages installed by pacman -U. That is a different mental model from the usual AUR helper, which typically fetches a snapshot, builds it, and installs the result with pacman -U, leaving a package the database does not really track and that a later system upgrade can quietly overwrite. aurutils instead keeps built packages in a repository on disk that pacman knows about, so the same install, query and removal commands work for AUR content as for anything else. The scripts are deliberately kept separate by task, with package searching, update checks and dependency computation living in different tools, and the whole set is described as helper tools for the AUR. ## A dispatcher script generated from a template The build layout makes the structure of the code visible. The top level holds aur.in, which is a template, and the Makefile turns it into the executable named aur by substituting two values with sed, the library directory and the version string. The library itself is a set of files under lib/ whose names start with aur-, collected by the Makefile into a variable and installed into a directory named after the program under the library prefix. The version comes from git describe, and if that returns nothing, because the tree was not cloned with tags, it falls back to the value 21. The install target is a list of explicit install calls, one per artefact: the dispatcher to the binary directory, the library files to the library directory, the section 1 and section 7 man pages to the groff man directories, the licence and the README to the documentation directory, the examples alongside them, an aurutils configuration directory under /etc, and then the shell completions and the perl parts through their own sub-makes. ## Installing and running it The documented install path is the AUR itself, with two choices. The release package is the recommended one and the git package tracks the master branch. Upgrade notices are posted on the Arch forums, and the README does not duplicate them, so that thread is where you find the notes for a new version. If you prefer to build from the repository yourself, the Makefile does the work and the install target honours the usual PREFIX override, with PREFIX defaulting to /usr and the shared, binary and library directories derived from it. The library directory that aur.in expects is exported as AURUTILS_LIB_DIR, which the Makefile derives from the library prefix under PREFIX. ```bash make ``` The one command the README gives for real use is the debug invocation, which is also the entry point for troubleshooting. ```bash AUR_DEBUG=1 aur >aurutils.log 2>&1 ``` That writes a log file which the troubleshooting section asks you to attach to a GitHub issue. ## The man pages are the documentation There is no long usage guide in the README, and that is deliberate. Documentation is included as man pages with groff typesetting, and the README says they provide a general overview of the various utilities with several examples. The detailed instructions for setting up a local repository, which is the step the whole design depends on, live in a specific section of the aur(1) man page under the heading CREATING A LOCAL REPOSITORY. The man1/ and man7/ directories in the repository are therefore the primary documentation, and the README points into them rather than repeating them. If you are evaluating this project, that man page section is the document to read, not the README. The man7 directory suggests a section 7 page for conventions, and the shell completions in completions/ are generated for bash and zsh by a dedicated make target, so the tools do declare their own options to the shell. ## A test suite made of shell scripts Testing a shell tool set does not look like a unit test framework, and this repository's approach is visible in the Makefile. The test target depends on the generated dispatcher and on shellcheck, and then it runs three things: a script named tests/parseopt-consistency, which checks that the option parsing agrees with the declared options, a script named tests/completion-bash, which checks the bash completion, and a recursive make into the perl directory to run its own tests. A separate shellcheck target runs shellcheck over every aur- prefixed library file with the gcc formatter and the 1071 exclusion, which is the check that keeps the library consistent with the shell it targets. The perl/ directory is a real part of the project rather than a leftover, since it has its own tests and its own install step, and the Makefile installs it as part of the main install target. The examples/ directory ships a small set of workflows named sync-asroot, sync-devel, sync-list, sync-rebuild, vercmp-devel and view-delta, which are installed as documentation and read as the intended usage patterns. ## The dependency on a healthy pacman and makepkg setup The troubleshooting section is the most honest part of the README, and it reads as a checklist rather than a fix. Before filing an issue you are asked to confirm that you use the latest release and its dependencies, and whether the problem reproduces from the master branch, that the package conforms to PKGBUILD(5) and the AUR package guidelines, that the package provides the correct metadata on the AUR RPC interface, and that it builds with makepkg -s or extra-x86_64-build. You are also asked whether the package uses internal makepkg functions, which is a reference to a known Arch bug report, and whether the problem is actually a misconfiguration of pacman, makepkg, sudoers, gpg or something else. That list tells you what the project assumes about your machine. It assumes an Arch installation with pacman and makepkg configured, with GPG working for package signing, with sudo rules set up for the parts that need root, and with a working path to the AUR RPC interface. Any of those missing turns a simple package install into a debugging session. The project also assumes you want local repositories, since the alternative it deliberately steps away from is the pacman -U workflow, and switching approaches is a change of mental model rather than a configuration flag. ## Version numbering, release cadence and licence The release tags are numbered 20.5.8, 20.5.7 and 20.5.6, and the most recent was published on 2026-02-23, with 20.5.7 on 2025-10-21 and 20.5.6 on 2025-09-28. The repository is not archived and the last push was on 2026-04-23, so the tree moves between releases, and the gap between the newest tag and the last commit is the place where unreleased changes live. The README asks users to check the latest release first and then ask whether the problem reproduces from the master branch, which is a two step process that assumes both are available. NEWS.md at the root carries the release notes, and upgrade notices also go to the Arch forum thread linked from the README. The licence is ISC, a short permissive grant with no copyleft obligation on anything you write with the scripts. The one operational cost of the tool set is that it is written for a moving target: the Arch packaging tools, the AUR RPC interface and the AUR package guidelines all change independently of this repository, so the checklist in the troubleshooting section is a maintenance burden the project hands to the user rather than absorbing. ## Conclusion aurutils fits an Arch user who installs AUR packages regularly and wants them tracked by pacman like any other repository package, and it fits a person who reads man pages for a living and wants a script set they can read and patch. It does not fit a machine that is not Arch based, and it does not fit a workflow built on pacman -U where a package is a tarball you keep and reinstall. Verify three things before switching: that your PKGBUILDs conform to PKGBUILD(5) and the AUR package guidelines, that the makepkg and gpg setup in your environment matches what the troubleshooting list assumes, and whether the version you would install is the release package aurutils or the master branch package aurutils-git, because the last push was on 2026-04-23 and the newest release tag is 20.5.8 from 2026-02-23. ## FAQ ### What is aurutils and what does it do? It is a collection of scripts to automate usage of the Arch User Repository, with package searching, update checks and dependency computation kept in separate tools. The chosen approach is local pacman repositories rather than foreign packages installed by pacman -U. ### How do I install aurutils on Arch? The README lists two packages, aurutils for the release version, which is recommended, and aurutils-git for the master branch. Detailed setup of the local repository is documented in the CREATING A LOCAL REPOSITORY section of the aur(1) man page. ### How do I create a debug log for an aurutils bug report? Run the command with AUR_DEBUG=1 and redirect both streams into aurutils.log, then attach that file to a new GitHub issue. Informal discussion happens in the #aurutils channel on Libera Chat. ### Does aurutils have a command line interface and shell completion? The dispatcher is a single executable built from the aur.in template, and the repository ships completions for bash and zsh generated by a dedicated make target. Documentation is provided as groff man pages in the man1 and man7 directories. ## Sources - [aurutils/aurutils on GitHub](https://github.com/aurutils/aurutils) - [Issues](https://github.com/aurutils/aurutils/issues) - [License: ISC](https://github.com/aurutils/aurutils/blob/master/LICENSE) - [README](https://github.com/aurutils/aurutils/blob/master/README.md) - [Releases](https://github.com/aurutils/aurutils/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aurutils-aurutils