AUGPRINT(1) Augeas AUGPRINT(1)

# [NAME](#NAME)

augprint - create an idempotent augtool script for a given file

# [SYNOPSIS](#SYNOPSIS)

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

# [DESCRIPTION](#DESCRIPTION)

**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](#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

```
  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"

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

## [Limitations](#Limitations)

*Append-only*

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 192.0.2.3 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

```
  #------
  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]"

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

# [OPTIONS](#OPTIONS)

[**-v**, **--verbose**](#v)

Include the original numbered paths as comments in the output

[**-p**, **--pretty**](#p)

Create more readable output by adding spaces and empty lines

[**-r**, **-rN**, **--regexp**, **--regexp**=*N*](#r)

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*](#l)

Use *LENS* for the given file; without this option, **augprint** uses the default lens for the file

[**-t** *targetfile*, **--target**=*targetfile*](#t)

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**](#s)

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)

# [EXAMPLES](#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](#Default_output)

"augprint /etc/hosts"

```
  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](#Verbose_output)

"augprint --verbose /etc/hosts"

```
  #   /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](#Rexexp_output)

"augprint --regexp=4 /etc/hosts"

```
  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.

## 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 '192.0.2.7   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='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)

# [ENVIRONMENT VARIABLES](#ENVIRONMENT_VARIABLES)

[**AUGEAS\_ROOT**](#AUGEAS_ROOT)

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

[**AUGEAS\_LENS\_LIB**](#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](#EXIT_STATUS)

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

# [FILES](#FILES)

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

# [AUTHOR](#AUTHOR)

George Hansper <george@hansper.id.au>

# [COPYRIGHT AND LICENSE](#COPYRIGHT_AND_LICENSE)

Copyright 2022 George Hansper

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

# [SEE ALSO](#SEE_ALSO)

[**augtool**(1)](/man/enterprise-packages/augeas/augtool.1)

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

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

2026-10-26 Augeas 1.15.0

---

Document: augprint(1) from augeas 1.15.0-r2 (Chainguard OS)
Source: https://github.com/hercules-team/augeas.git