Loading specific files

Since version 0.5.0, it is possible to load specific files with Augeas. This tutorial takes you through it using augtool, but this is also possible using the API.

Start augtool without loading files. This is not mandatory but saves some time:

  augtool --noload

In my case, I would like to parse ~/.dput.cf, which uses the Dput.lns lens (from dput.aug). It is not parsed by default because it is in a home directory. Let's see what Augeas already knows about the Dput module. Informations about Augeas modules are stored in /augeas/load in the Augeas tree:

  augtool> print /augeas/load/Dput/
  /augeas/load/Dput
  /augeas/load/Dput/lens = "@Dput"
  /augeas/load/Dput/incl[1] = "/home/rpinson/.dput.cf"
  /augeas/load/Dput/incl[2] = "/etc/dput.cf"
  /augeas/load/Dput/excl[1] = "*.augnew"
  /augeas/load/Dput/excl[2] = "*.augsave"
  /augeas/load/Dput/excl[3] = "*.rpmsave"
  /augeas/load/Dput/excl[4] = "*.rpmnew"
  /augeas/load/Dput/excl[5] = "*~"

The notation @Dput means 'use the lens that is marked for autoload in the Dput module'; the lens can also be specified with a fully qualified name, for example, as Dput.lns. The incl and excl entries are glob patterns, and only files that match at least one incl and no excl will be transformed with the lens.

Now Augeas is ready to parse /home/rpinson.dput.cf. Let's try:

  augtool> load
  augtool> ls /files/home/rpinson/.dput.cf
  target[1]/ = dop/experimental
  target[2]/ = dop/messagingsuite
  target[3]/ = dop/gforge
  target[4]/ = dop/gforge-dev
  target[5]/ = dop/ke-preprod

Loading even less

By default, augtool searches for .aug files on its load path and reads them in to find all transforms marked for autoload. It creates appropriate entries under /augeas/load for those transforms and then does a load of all the files matching a transform. When you use the --noload option with augtool, Augeas still has to read all its modules and create the /augeas/load hierarchy.

For a minimal startup, you can pass the --noautoload option, which keeps Augeas from even looking for modules and creating the /augeas/load hierarchy. Once augtool starts, you can set up entries under /augeas/load manually (though you can't use the @Module notation for a lens, only Module.lens) and Augeas will dynamically load the needed lenses, and then files when you issue a load

For example, if you want to only modify /etc/fstab, using the Fstab lens. In order to do that, we can start augtool without loading any lenses:

 $ augtool --noautoload
 augtool> print /augeas/load
 /augeas/load

The print command shows us that no lenses are known in the session. We can now tell Augeas to load the Fstab lens and to include /etc/fstab for it:

 augtool> set /augeas/load/Fstab/lens "Fstab.lns"
 augtool> set /augeas/load/Fstab/incl "/etc/fstab"
 augtool> print /augeas/load
 /augeas/load
 /augeas/load/Fstab
 /augeas/load/Fstab/lens = "Fstab.lns"
 /augeas/load/Fstab/incl = "/etc/fstab"

We can now call load and list the files in /files/etc:

 augtool> load
 augtool> ls /files/etc
 fstab/ = (none)

Loading even less in C

The --noload option for augtool corresponds to passing the flag AUG_NO_LOAD to aug_init, and --noautoload corresponds to passing the flag AUG_NO_MODL_AUTOLOAD