Your company here — click to reach over 10,000 unique daily visitors

augprint - Man Page

create an idempotent augtool script for a given file


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


augprint creates an augtool script for a given FILE consisting primarily of set commands.

The resulting augtool script is designed to be idempotent, and will not result in any changes when applied to the original file.

augprint replaces each numbered location in the tree with a path-expression that uniquely identifies the position using the values within that position.

This makes the path-expression independant of the position-number, and thereby applicable to files which in which the same data may exist at an alternate position-number

See "Examples" for sample output

Regexp output

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

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

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

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

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

augprint will choose a longer regular expression than N if multiple values would match using the N character regular expression.



The output is based primarily on set operations. The set operation can only:

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 does not already exist, it will be created as the last entry in /etc/hosts

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.

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

  #------   defaultdns

augprint would produce the output

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

Notice how #comment paths have [1] and [2] appended respectively to the [expr]

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


-v,  --verbose

Include the original numbered paths as comments in the output

-p,  --pretty

Create more readable output by adding spaces and empty lines

-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='']/ipaddr ''

IMPORTANT: The resulting output will no longer create a new entry for 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)


These examples use the following /etc/hosts file as the FILE   localhost localhost.localdomain localhost4 localhost4.localdomain4   dns-a   dns-b

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

  /files/etc/hosts/1/ipaddr = ""
  /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/ipaddr = ""
  /files/etc/hosts/2/canonical = "dns-a"
  /files/etc/hosts/3/ipaddr = ""
  /files/etc/hosts/3/canonical = "dns-b"

Default output

augprint /etc/hosts

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

Verbose output

augprint --verbose /etc/hosts

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

Rexexp output

augprint --regexp=4 /etc/hosts

  set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/ipaddr ''
  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 ''
  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 ''
  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.

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

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.

a) copy /etc/hosts to a new location

   cp /etc/hosts ~

b) edit ~/hosts to suit

   echo '   defaultdns' >> ~/hosts

c) Run augprint as follows

   augprint --target /etc/hosts ~/hosts

d) Copy the relevant part of the output to an augtool script or other Augeas client

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

Notice that augprint has generated paths corresponding to --target (/etc/hosts) instead of the FILE argument (~/hosts)

Environment Variables


The effective file system root, defaults to '/'.


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.


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


George Hansper <george@hansper.id.au>

See Also


Augeas project homepage <https://www.augeas.net/>

Augeas path expressions <https://github.com/hercules-team/augeas/wiki/Path-expressions>


2023-07-14 Augeas 1.14.1