--- name: "augprint" section: "1" platform: "linux" package: "augeas" version: "1.15.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/augprint" --- # augprint(1) create an idempotent augtool script for a given file ## NAME augprint - create an idempotent augtool script for a given file ## SYNOPSIS augprint \[--pretty\|-p\] \[--regexp\[=n\]\|-r\[n\]\] \[--noseq\|-s\] \[--verbose\|-v\] \[--lens name\|-l name\] \[--target /target\|-t /target\] FILE ## 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 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 *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 - **-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**, **-r***N*, **--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) ## 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"` ``` 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"` ``` # /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"` ``` 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 - **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. ## FILES Lenses and schema definitions in */usr/share/augeas/lenses* and */usr/share/augeas/lenses/dist* ## AUTHOR George Hansper \ ## 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 [**augtool**(1)](/augtool/1.md) **Augeas** project homepage \ **Augeas** path expressions \