-.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
. ds PI \(*p
. ds L" ``
. ds R" ''
+. ds C`
+. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.ie \nF \{\
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
..
-. nr % 0
-. rr F
-.\}
-.el \{\
-. de IX
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+. if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
..
+. if !\nF==2 \{\
+. nr % 0
+. nr F 2
+. \}
+. \}
.\}
+.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "AUGTOOL 1"
-.TH AUGTOOL 1 "2011-12-01" "Augeas 0.9.0" "Augeas"
+.TH AUGTOOL 1 "2022-10-24" "Augeas 1.13.0" "Augeas"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
native config files.
.PP
augtool provides a command line interface to the generated tree. \s-1COMMAND\s0
-can be a single command as described under \*(L"\s-1COMMANDS\s0\*(R". When called with
-no \s-1COMMAND\s0, it reads commands from standard input until an end-of-file is
+can be a single command as described under \*(L"\s-1COMMANDS\*(R"\s0. When called with
+no \s-1COMMAND,\s0 it reads commands from standard input until an end-of-file is
encountered.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IX Item "-I, --include=DIR"
Add \s-1DIR\s0 to the module loadpath. Can be given multiple times. The
directories set here are searched before any directories specified in the
-\&\s-1AUGEAS_LENS_LIB\s0 environment variable, and before the default directory
-\&\fI/usr/share/augeas/lenses\fR.
+\&\s-1AUGEAS_LENS_LIB\s0 environment variable, and before the default directories
+\&\fI/usr/share/augeas/lenses\fR and \fI/usr/share/augeas/lenses/dist\fR.
+.IP "\fB\-t\fR, \fB\-\-transform\fR=\fI\s-1XFM\s0\fR" 4
+.IX Item "-t, --transform=XFM"
+Add a file transform; uses the 'transform' command syntax,
+e.g. \f(CW\*(C`\-t \*(AqFstab incl /etc/fstab.bak\*(Aq\*(C'\fR.
+.IP "\fB\-l\fR, \fB\-\-load\-file\fR=\fI\s-1FILE\s0\fR" 4
+.IX Item "-l, --load-file=FILE"
+Load an individual \s-1FILE\s0 into the tree. The lens to use is determined
+automatically (based on autoload information in the lenses) and will be the
+same that is used for this file when the entire tree is loaded. The option
+can be specified multiple times to load several files, e.g. \f(CW\*(C`\-l /etc/fstab
+\&\-l /etc/hosts\*(C'\fR. This lens implies \f(CW\*(C`\-\-noload\*(C'\fR so that only the files
+specified with this option will be loaded.
.IP "\fB\-f\fR, \fB\-\-file\fR=\fI\s-1FILE\s0\fR" 4
.IX Item "-f, --file=FILE"
-Read commands from \s-1FILE\s0.
+Read commands from \s-1FILE.\s0
.IP "\fB\-i\fR, \fB\-\-interactive\fR" 4
.IX Item "-i, --interactive"
Read commands from the terminal. When combined with \fB\-f\fR or redirection of
stdin, drop into an interactive session after executing the commands from
the file.
-.IP "\fB\-e\fR" 4
-.IX Item "-e"
+.IP "\fB\-e\fR, \fB\-\-echo\fR" 4
+.IX Item "-e, --echo"
When reading commands from a file via stdin, echo the commands before
printing their output.
.IP "\fB\-s\fR, \fB\-\-autosave\fR" 4
creates no entries under \f(CW\*(C`/augeas/load\*(C'\fR whatsoever; to read any files,
they need to be set up manually and loading must be initiated with a
\&\f(CW\*(C`load\*(C'\fR command. Using this option gives the fastest startup.
+.IP "\fB\-\-span\fR" 4
+.IX Item "--span"
+Load span positions for nodes in the tree, as they relate to the original
+file. Enables the use of the \fBspan\fR command to retrieve position data.
+.IP "\fB\-\-timing\fR" 4
+.IX Item "--timing"
+After executing each command, print how long, in milliseconds, executing
+the command took. This makes it easier to spot slow queries, usually
+through \fBmatch\fR commands, and allows exploring alternative queries that
+yield the same result but might be faster.
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
Print version information and exit. The version is also in the tree under
every node regardless of its label. Sibling nodes with identical labels can
be distinguished by appending \f(CW\*(C`[N]\*(C'\fR to their label to match the N\-th
sibling with such a label. The last sibling with a specific label can be
-reached as \f(CW\*(C`[last()]\*(C'\fR. See \*(L"\s-1EXAMPLES\s0\*(R" for some examples of this.
+reached as \f(CW\*(C`[last()]\*(C'\fR. See \*(L"\s-1EXAMPLES\*(R"\s0 for some examples of this.
+.SS "\s-1ADMIN COMMANDS\s0"
+.IX Subsection "ADMIN COMMANDS"
+The following commands control the behavior of Augeas and augtool itself.
+.IP "\fBhelp\fR" 4
+.IX Item "help"
+Print this help text
+.IP "\fBload\fR" 4
+.IX Item "load"
+Load files according to the transforms in \f(CW\*(C`/augeas/load\*(C'\fR.
.IP "\fBquit\fR" 4
.IX Item "quit"
Exit the program
+.IP "\fBretrieve\fR <\s-1LENS\s0> <\s-1NODE_IN\s0> <\s-1PATH\s0> <\s-1NODE_OUT\s0>" 4
+.IX Item "retrieve <LENS> <NODE_IN> <PATH> <NODE_OUT>"
+Transform tree at \s-1PATH\s0 back into text using lens \s-1LENS\s0 and store the
+resulting string at \s-1NODE_OUT.\s0 Assume that the tree was initially read in
+with the same lens and the string stored at \s-1NODE_IN\s0 as input.
+.IP "\fBsave\fR" 4
+.IX Item "save"
+Save all pending changes to disk. Unless either the \fB\-b\fR or \fB\-n\fR
+command line options are given, files are changed in place.
+.IP "\fBstore\fR <\s-1LENS\s0> <\s-1NODE\s0> <\s-1PATH\s0>" 4
+.IX Item "store <LENS> <NODE> <PATH>"
+Parse \s-1NODE\s0 using \s-1LENS\s0 and store the resulting tree at \s-1PATH.\s0
+.IP "\fBtransform\fR <\s-1LENS\s0> <\s-1FILTER\s0> <\s-1FILE\s0>" 4
+.IX Item "transform <LENS> <FILTER> <FILE>"
+Add a transform for \s-1FILE\s0 using \s-1LENS.\s0 The \s-1LENS\s0 may be a module name or a
+full lens name. If a module name is given, then \*(L"lns\*(R" will be the lens
+assumed. The \s-1FILTER\s0 must be either \*(L"incl\*(R" or \*(L"excl\*(R". If the filter is
+\&\*(L"incl\*(R", the \s-1FILE\s0 will be parsed by the \s-1LENS.\s0 If the filter is \*(L"excl\*(R",
+the \s-1FILE\s0 will be excluded from the \s-1LENS. FILE\s0 may contain wildcards.
+.IP "\fBload-file\fR <\s-1FILE\s0>" 4
+.IX Item "load-file <FILE>"
+Load a specific \s-1FILE,\s0 automatically determining the proper lens from the
+information in \fI/augeas/load\fR; without further intervention, the lens that
+would oridnarily be used for this file will be used.
+.SS "\s-1READ COMMANDS\s0"
+.IX Subsection "READ COMMANDS"
+The following commands are used to retrieve data from the Augeas tree.
+.IP "\fBdump-xml\fR \fI[<\s-1PATH\s0>]\fR" 4
+.IX Item "dump-xml [<PATH>]"
+Print entries in the tree as \s-1XML.\s0 If \s-1PATH\s0 is given, printing starts there,
+otherwise the whole tree is printed.
+.IP "\fBget\fR <\s-1PATH\s0>" 4
+.IX Item "get <PATH>"
+Print the value associated with \s-1PATH\s0
+.IP "\fBlabel\fR <\s-1PATH\s0>" 4
+.IX Item "label <PATH>"
+Get and print the label associated with \s-1PATH\s0
.IP "\fBls\fR <\s-1PATH\s0>" 4
.IX Item "ls <PATH>"
List the direct children of \s-1PATH\s0
.IP "\fBmatch\fR <\s-1PATTERN\s0> [<\s-1VALUE\s0>]" 4
.IX Item "match <PATTERN> [<VALUE>]"
-Find all paths that match \s-1PATTERN\s0. If \s-1VALUE\s0 is given, only the matching
+Find all paths that match \s-1PATTERN.\s0 If \s-1VALUE\s0 is given, only the matching
paths whose value equals \s-1VALUE\s0 are printed
-.IP "\fBrm\fR <\s-1PATH\s0>" 4
-.IX Item "rm <PATH>"
-Delete \s-1PATH\s0 and all its children from the tree
+.IP "\fBprint\fR \fI[<\s-1PATH\s0>]\fR" 4
+.IX Item "print [<PATH>]"
+Print entries in the tree. If \s-1PATH\s0 is given, printing starts there,
+otherwise the whole tree is printed
+.IP "\fBspan\fR <\s-1PATH\s0>" 4
+.IX Item "span <PATH>"
+Print the name of the file from which the node \s-1PATH\s0 was generated, as well
+as information about the positions in the file corresponding to the label,
+the value, and the entire node. \s-1PATH\s0 must match exactly one node.
+.Sp
+You need to run 'set /augeas/span enable' prior to loading files to enable
+recording of span information. It is disabled by default.
+.SS "\s-1WRITE COMMANDS\s0"
+.IX Subsection "WRITE COMMANDS"
+The following commands are used to modify the Augeas tree.
+.IP "\fBclear\fR <\s-1PATH\s0>" 4
+.IX Item "clear <PATH>"
+Set the value for \s-1PATH\s0 to \s-1NULL.\s0 If \s-1PATH\s0 is not in the tree yet, it and all
+its ancestors will be created.
+.IP "\fBclearm\fR <\s-1BASE\s0> <\s-1SUB\s0>" 4
+.IX Item "clearm <BASE> <SUB>"
+Clear multiple nodes values in one operation. Find or create a node matching \s-1SUB\s0
+by interpreting \s-1SUB\s0 as a path expression relative to each node matching
+\&\s-1BASE.\s0 If \s-1SUB\s0 is '.', the nodes matching \s-1BASE\s0 will be modified.
+.IP "\fBins\fR \fI<\s-1LABEL\s0>\fR \fI<\s-1WHERE\s0>\fR \fI<\s-1PATH\s0>\fR" 4
+.IX Item "ins <LABEL> <WHERE> <PATH>"
+Insert a new node with label \s-1LABEL\s0 right before or after \s-1PATH\s0 into the
+tree. \s-1WHERE\s0 must be either 'before' or 'after'.
+.IP "\fBinsert\fR \fI<\s-1LABEL\s0>\fR \fI<\s-1WHERE\s0>\fR \fI<\s-1PATH\s0>\fR" 4
+.IX Item "insert <LABEL> <WHERE> <PATH>"
+Alias of \fBins\fR.
.IP "\fBmv\fR <\s-1SRC\s0> <\s-1DST\s0>" 4
.IX Item "mv <SRC> <DST>"
-Move node \s-1SRC\s0 to \s-1DST\s0. \s-1SRC\s0 must match exactly one node in the tree. \s-1DST\s0
+Move node \s-1SRC\s0 to \s-1DST. SRC\s0 must match exactly one node in the tree. \s-1DST\s0
+must either match exactly one node in the tree, or may not exist yet. If
+\&\s-1DST\s0 exists already, it and all its descendants are deleted. If \s-1DST\s0 does not
+exist yet, it and all its missing ancestors are created.
+.IP "\fBmove\fR <\s-1SRC\s0> <\s-1DST\s0>" 4
+.IX Item "move <SRC> <DST>"
+Alias of \fBmv\fR.
+.IP "\fBcp\fR <\s-1SRC\s0> <\s-1DST\s0>" 4
+.IX Item "cp <SRC> <DST>"
+Copy node \s-1SRC\s0 to \s-1DST. SRC\s0 must match exactly one node in the tree. \s-1DST\s0
must either match exactly one node in the tree, or may not exist yet. If
\&\s-1DST\s0 exists already, it and all its descendants are deleted. If \s-1DST\s0 does not
exist yet, it and all its missing ancestors are created.
+.IP "\fBcopy\fR <\s-1SRC\s0> <\s-1DST\s0>" 4
+.IX Item "copy <SRC> <DST>"
+Alias of \fBcp\fR.
+.IP "\fBrename\fR <\s-1SRC\s0> <\s-1LBL\s0>" 4
+.IX Item "rename <SRC> <LBL>"
+Rename the label of all nodes matching \s-1SRC\s0 to \s-1LBL.\s0
+.IP "\fBrm\fR <\s-1PATH\s0>" 4
+.IX Item "rm <PATH>"
+Delete \s-1PATH\s0 and all its children from the tree
.IP "\fBset\fR <\s-1PATH\s0> <\s-1VALUE\s0>" 4
.IX Item "set <PATH> <VALUE>"
-Associate \s-1VALUE\s0 with \s-1PATH\s0. If \s-1PATH\s0 is not in the tree yet,
+Associate \s-1VALUE\s0 with \s-1PATH.\s0 If \s-1PATH\s0 is not in the tree yet,
it and all its ancestors will be created.
-.IP "\fBclear\fR <\s-1PATH\s0>" 4
-.IX Item "clear <PATH>"
-Set the value for \s-1PATH\s0 to \s-1NULL\s0. If \s-1PATH\s0 is not in the tree yet, it and all
-its ancestors will be created.
-.IP "\fBsetm\fR <\s-1BASE\s0> <\s-1SUB\s0> <\s-1VALUE\s0>" 4
-.IX Item "setm <BASE> <SUB> <VALUE>"
+.IP "\fBsetm\fR <\s-1BASE\s0> <\s-1SUB\s0> [<\s-1VALUE\s0>]" 4
+.IX Item "setm <BASE> <SUB> [<VALUE>]"
Set multiple nodes in one operation. Find or create a node matching \s-1SUB\s0 by
interpreting \s-1SUB\s0 as a path expression relative to each node matching
-\&\s-1BASE\s0. If \s-1SUB\s0 is '.', the nodes matching \s-1BASE\s0 will be modified.
-.IP "\fBget\fR <\s-1PATH\s0>" 4
-.IX Item "get <PATH>"
-Print the value associated with \s-1PATH\s0
-.IP "\fBprint\fR \fI[<\s-1PATH\s0>]\fR" 4
-.IX Item "print [<PATH>]"
-Print entries in the tree. If \s-1PATH\s0 is given, printing starts there,
-otherwise the whole tree is printed
-.IP "\fBdump-xml\fR \fI[<\s-1PATH\s0>]\fR \fI[<\s-1FILENAME\s0>]\fR" 4
-.IX Item "dump-xml [<PATH>] [<FILENAME>]"
-Print entries in the tree as \s-1XML\s0. If \s-1PATH\s0 is given, printing starts there,
-otherwise the whole tree is printed. If \s-1FILENAME\s0 is given, the \s-1XML\s0 is saved
-to the given file.
-.IP "\fBins\fR \fI<\s-1LABEL\s0>\fR \fI<\s-1WHERE\s0>\fR \fI<\s-1PATH\s0>\fR" 4
-.IX Item "ins <LABEL> <WHERE> <PATH>"
-Insert a new node with label \s-1LABEL\s0 right before or after \s-1PATH\s0 into the
-tree. \s-1WHERE\s0 must be either 'before' or 'after'.
-.IP "\fBsave\fR" 4
-.IX Item "save"
-Save all pending changes to disk. Unless either the \fB\-b\fR or \fB\-n\fR
-command line options are given, files are changed in place.
-.IP "\fBload\fR" 4
-.IX Item "load"
-Load files according to the transforms in \f(CW\*(C`/augeas/load\*(C'\fR.
-.IP "\fBdefvar\fR <\s-1NAME\s0> <\s-1EXPR\s0>" 4
-.IX Item "defvar <NAME> <EXPR>"
-Define the variable \s-1NAME\s0 to the result of evaluating \s-1EXPR\s0. The variable
-can be used in path expressions as \f(CW$NAME\fR. Note that \s-1EXPR\s0 is evaluated when
-the variable is defined, not when it is used.
+\&\s-1BASE.\s0 If \s-1SUB\s0 is '.', the nodes matching \s-1BASE\s0 will be modified.
+.IP "\fBtouch\fR <\s-1PATH\s0>" 4
+.IX Item "touch <PATH>"
+Create \s-1PATH\s0 with the value \s-1NULL\s0 if it is not in the tree yet. All its
+ancestors will also be created. These new tree entries will appear
+last amongst their siblings.
+.SS "\s-1PATH EXPRESSION COMMANDS\s0"
+.IX Subsection "PATH EXPRESSION COMMANDS"
+The following commands help when working with path expressions.
.IP "\fBdefnode\fR <\s-1NAME\s0> <\s-1EXPR\s0> [<\s-1VALUE\s0>]" 4
.IX Item "defnode <NAME> <EXPR> [<VALUE>]"
-Define the variable \s-1NAME\s0 to the result of evaluating \s-1EXPR\s0, which must be a
+Define the variable \s-1NAME\s0 to the result of evaluating \s-1EXPR,\s0 which must be a
nodeset. If no node matching \s-1EXPR\s0 exists yet, one is created and \s-1NAME\s0 will
-refer to it. If \s-1VALUE\s0 is given, this is the same as 'set \s-1EXPR\s0 \s-1VALUE\s0'; if
+refer to it. If \s-1VALUE\s0 is given, this is the same as 'set \s-1EXPR VALUE\s0'; if
\&\s-1VALUE\s0 is not given, the node is created as if with 'clear \s-1EXPR\s0' would and
\&\s-1NAME\s0 refers to that node.
-.IP "\fBspan\fR <\s-1PATH\s0>" 4
-.IX Item "span <PATH>"
-Print the name of the file from which the node \s-1PATH\s0 was generated, as well
-as information about the positions in the file corresponding to the label,
-the value, and the entire node. \s-1PATH\s0 must match exactly one node.
-.Sp
-You need to run 'set /augeas/span enable' prior to loading files to enable
-recording of span information. It is disabled by default.
-.IP "\fBhelp\fR" 4
-.IX Item "help"
-Print this help text
+.IP "\fBdefvar\fR <\s-1NAME\s0> <\s-1EXPR\s0>" 4
+.IX Item "defvar <NAME> <EXPR>"
+Define the variable \s-1NAME\s0 to the result of evaluating \s-1EXPR.\s0 The variable
+can be used in path expressions as \f(CW$NAME\fR. Note that \s-1EXPR\s0 is evaluated when
+the variable is defined, not when it is used.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.IP "\fB\s-1AUGEAS_ROOT\s0\fR" 4
.IX Item "AUGEAS_LENS_LIB"
Colon separated list of directories with lenses. Directories specified here
are searched after any directories set with the \fB\-I\fR command line option,
-but before the default directory \fI/usr/share/augeas/lenses\fR
+but before the default directories \fI/usr/share/augeas/lenses\fR and
+\&\fI/usr/share/augeas/lenses/dist\fR
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Normally, exit status is 0. If one or more commands fail, the exit status
.Ve
.SH "FILES"
.IX Header "FILES"
-Lenses and schema definitions in \fI/usr/share/augeas/lenses\fR
+Lenses and schema definitions in \fI/usr/share/augeas/lenses\fR and
+\&\fI/usr/share/augeas/lenses/dist\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
-.Vb 1
-\& David Lutterkort <dlutter@redhat.com>
-.Ve
+David Lutterkort <lutter@watzmann.net>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
-Copyright 2007\-2011 Red Hat Inc.
+Copyright 2007\-2016 David Lutterkort
.PP
Augeas (and augtool) are distributed under the \s-1GNU\s0 Lesser General Public
License (\s-1LGPL\s0)
.IX Header "SEE ALSO"
\&\fBAugeas\fR project homepage <http://www.augeas.net/>
.PP
+\&\fBAugeas\fR path expressions <https://github.com/hercules\-team/augeas/wiki/Path\-expressions>
+.PP
augparse
+.PP
+augprint
projects / platform / upstream / augeas.git / blobdiff