AUGPRINT(1)

📦
version 1.15.0 · 9 versions
, in arch rolling

💅 AUGPRINT(1) — the Augeas girlie's guide 💅

okay so bestie, welcome to augprint, part of Augeas (yes, that Augeas). Sit down, hydrate, and let me tell you about the little tool that writes augtool scripts for you so you don't have to. 🫶

✨ NAME ✨

augprint — create an idempotent augtool script for a given file. that's it, that's the whole job, and it does it beautifully. 💖

✨ SYNOPSIS ✨

augprint [--pretty|-p] [--regexp[=n]|-r[n]] [--noseq|-s] [--verbose|-v]
[--lens name|-l name] [--target /target|-t /target] FILE

✨ DESCRIPTION ✨

So what does augprint actually do? It creates an augtool script for a given FILE that's made up, primarily, of "set" commands. Simple concept, iconic execution.

The resulting augtool script is designed to be idempotent — meaning if you apply it to the original file, literally nothing changes. zero. nada. no cap. 🎀

Here's the cute part: augprint replaces each numbered location in the tree with a path-expression that uniquely identifies that position using the values within that position. so instead of "position 3," it's like "the one where the ipaddr is 127.0.0.1," iykyk.

That makes the path-expression independant of the position-number, and therefore applicable to files in which the same data may exist at an alternate position-number. slay. ✨

See "Examples" for sample output — there's a whole section down there and it's honestly the best part.

🌸 Regexp output 🌸

By default, augprint produces path-expressions made up of simple equality "=" comparisions:

set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1'

The option --regexp changes the output to produce regular expression comparisions instead:

set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\.0\\..*')]/ipaddr '127.0.0.1'

The minimum length N of the regular expression can be specified using "--regexp=N".

And listen — augprint will choose a longer regular expression than N if multiple values would match using the N character regular expression. she's thorough like that. 💅

💀 Limitations 💀

🦋 Append-only 🦋

The output is based primarily on set operations. and the set operation can only do two things, bestie:

a) change an existing value in-situ

b) append a new value after the last position in the group

This means that when an entry is re-created, it may not be in the same position as originally intended. ie if the entry for 192.0.2.3 does not already exist, it will be created as the last entry in /etc/hosts. it's giving "new kid at the end of the line." 😭

Often, such out-of-sequence entries will not matter to the resulting configuration file. If it does matter, further manual editing of the "augtool" script will be required. sorry babe.

🍓 Repeated Values 🍓

augprint is not always successful in finding a path-expression which is unique to a position. In this case augprint appends a position to an expression which is not unique.

This occurs in particular if there are repeated values within the file.

For an /etc/hosts file of

#------
192.0.2.3   defaultdns
#------

augprint would produce the output

set /files/etc/hosts/#comment[.='--------'][1] '--------'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/ipaddr '192.0.2.3'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/canonical 'defaultdns'
set /files/etc/hosts/#comment[.='--------'][2] '--------'

Notice how "#comment" paths have "[1]" and "[2]" appended respectively to the "[expr]". the way that it just numbers them when it has to?? iconic.

Other paths which do have unique path-expressions are not directly affected. 🧚

✨ OPTIONS ✨

  • -v, --verbose — Include the original numbered paths as comments in the output. little receipts in the comments, we love to see it. 🙈
  • -p, --pretty — Create more readable output by adding spaces and empty lines. she's aesthetic now. 🎀
  • -r, -rN, --regexp, --regexp=N — Generate regular expressions to match values, using a minumum length of N characters from the value.
    • N can be omitted and defaults to 8. ⭐
  • -l, --lens=LENS — Use LENS for the given file; without this option, augprint uses the default lens for the file. 🦋
  • -t targetfile, --target=targetfile — Generate the script for the FILE specified as if its path was really targetfile.
    • This will apply the lens corresponding to targetfile to FILE and modifying the resulting path-expressions of FILE to correspond to targetfile. 💫
    • targetfile must be the full path name, starting with a /.
    • See "Examples" for how --target can be used in practice.
  • -s, --noseq — Do not use "seq::*" in the output, use "*" instead. For example:
set /files/etc/hosts/*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1'
IMPORTANT: The resulting output will no longer create a new entry for 127.0.0.1 if none already exists. The "--noseq" option exists so that the resulting paths can be used with augeas versions prior to 1.13.0 (subject to this limitation). like, she'll work, but she's on her old-version behavior era. 💀

✨ EXAMPLES ✨

These examples use the following /etc/hosts file as the FILE:

127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
192.0.2.3   dns-a
192.0.2.4   dns-b

The output from "augtool 'print /files/etc/hosts'" would be:

/files/etc/hosts
/files/etc/hosts/1
/files/etc/hosts/1/ipaddr = "127.0.0.1"
/files/etc/hosts/1/canonical = "localhost"
/files/etc/hosts/1/alias[1] = "localhost.localdomain"
/files/etc/hosts/1/alias[2] = "localhost4"
/files/etc/hosts/1/alias[3] = "localhost4.localdomain4"
/files/etc/hosts/2
/files/etc/hosts/2/ipaddr = "192.0.2.3"
/files/etc/hosts/2/canonical = "dns-a"
/files/etc/hosts/3
/files/etc/hosts/3/ipaddr = "192.0.2.4"
/files/etc/hosts/3/canonical = "dns-b"

🌈 Default output 🌈

"augprint /etc/hosts" gives you:

set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/canonical 'localhost'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost.localdomain'] 'localhost.localdomain'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost4'] 'localhost4'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost4.localdomain4'] 'localhost4.localdomain4'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/ipaddr '192.0.2.3'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/canonical 'dns-a'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.4']/ipaddr '192.0.2.4'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.4']/canonical 'dns-b'

⭐ Verbose output ⭐

"augprint --verbose /etc/hosts" gives you:

#   /files/etc/hosts
#   /files/etc/hosts/1
#   /files/etc/hosts/1/ipaddr  '127.0.0.1'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1'
#   /files/etc/hosts/1/canonical  'localhost'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/canonical 'localhost'
#   /files/etc/hosts/1/alias[1]  'localhost.localdomain'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost.localdomain'] 'localhost.localdomain'
...

🧚 Rexexp output 🧚

"augprint --regexp=4 /etc/hosts" gives you:

set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/ipaddr '127.0.0.1'
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/canonical 'localhost'
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost\\..*')] 'localhost.localdomain'
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost4')] 'localhost4'
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost4\\..*')] 'localhost4.localdomain4'
set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.3')]/ipaddr '192.0.2.3'
set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.3')]/canonical 'dns-a'
set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.4')]/ipaddr '192.0.2.4'
set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.4')]/canonical 'dns-b'

Note that although a minimum length of 4 has been specified, augprint will choose longer regular expressions as needed to ensure a unique match. she said "4 is the floor, not the ceiling." 💅

🦋 Using --lens 🦋

If a file is not assocatiated with a lens by default, --lens lensname can be used to specify a lens.

When --lens is specified, the output is prefixed with suitable "transform" and "load-file" statements, as required to complete the augtool script, and a setm statement to exclude other autoloaded lenses.

"augprint --lens shellvars /etc/skel/.bashrc":

setm /augeas/load/*[incl='/etc/skel/.bashrc' and label() != 'shellvars']/excl '/etc/skel/.bashrc'
transform shellvars incl /etc/skel/.bashrc
load-file /etc/skel/.bashrc
set /files/etc/skel/.bashrc/#comment[.='.bashrc'] '.bashrc'
set /files/etc/skel/.bashrc/#comment[.='Source global definitions'] 'Source global definitions'
set /files/etc/skel/.bashrc/@if[.='[ -f /etc/bashrc ]'] '[ -f /etc/bashrc ]'
set /files/etc/skel/.bashrc/@if[.='[ -f /etc/bashrc ]']/.source '/etc/bashrc'
set /files/etc/skel/.bashrc/#comment[.='User specific environment'] 'User specific environment'
...

The lenses "simplelines" "shellvars" are most commonly useful as lenses for files that do not have a specific lens. keep those two in your back pocket, bestie. 🎀

💖 Using --target 💖

In order to prepare an augtool script intended for a given file, it may be desired to copy the file to another location, rather than editting the original file.

The option --target simplifies this process. here's the whole glow-up routine:

  1. copy /etc/hosts to a new location
cp /etc/hosts ~
  1. edit ~/hosts to suit
echo '192.0.2.7   defaultdns' >> ~/hosts
  1. Run "augprint" as follows
augprint --target /etc/hosts ~/hosts
  1. Copy the relevant part of the output to an augtool script or other Augeas client
set /files/etc/hosts/seq::*[ipaddr='192.0.2.7']/ipaddr '192.0.2.7'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.7']/canonical 'defaultdns'

Notice that "augprint" has generated paths corresponding to --target (/etc/hosts) instead of the FILE argument (~/hosts). she said "I know what you meant." 👑

✨ ENVIRONMENT VARIABLES ✨

  • AUGEAS_ROOT — The effective file system root, defaults to '/'.
  • AUGEAS_LENS_LIB — Colon separated list of directories with lenses. Directories specified here are searched before the default directories /usr/share/augeas/lenses and /usr/share/augeas/lenses/dist.

✨ EXIT STATUS ✨

The exit status is 0 when the command was successful and 1 if any error occurred. binary queen. 💅

✨ FILES ✨

Lenses and schema definitions in /usr/share/augeas/lenses and /usr/share/augeas/lenses/dist.

✨ AUTHOR ✨

George Hansper <george@hansper.id.au> — thank you king 🫶

Copyright 2022 George Hansper

Augeas (and augprint) are distributed under the GNU Lesser General Public License (LGPL), version 2.1.

✨ SEE ALSO ✨

okay that's the whole page, bestie 💜 — this was Augeas 1.15.0, dated 2026-09-29, and yes she's still serving AUGPRINT(1). go write some idempotent scripts and text me when you're done. 🦋✨

📦 where this page comes from