fish: <! cmd executes a shell command and inlines the resulting commands.

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 21f25bd..5ec6689 100644 (file)
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -676,6 +676,32 @@ C<local/remote-data.tar.gz>.  (See C<tgz-out>).
 To change the local directory, use the C<lcd> command.  C<!cd> will
 have no effect, due to the way that subprocesses work in Unix.
 
+=head2 LOCAL COMMANDS WITH INLINE EXECUTION
+
+If a line starts with I<E<lt>!> then the shell command is executed (as
+for I<!>), but subsequently any output (stdout) of the shell command
+is parsed and executed as guestfish commands.
+
+Thus you can use shell script to construct arbitrary guestfish
+commands which are then parsed by guestfish.
+
+For example it is tedious to create a sequence of files
+(eg. C</foo.1> through C</foo.100>) using guestfish commands
+alone.  However this is simple if we use a shell script to
+create the guestfish commands for us:
+
+ <! for n in `seq 1 100`; do echo write /foo.$n $n; done
+
+or with names like C</foo.001>:
+
+ <! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done
+
+When using guestfish interactively it can be helpful to just run the
+shell script first (ie. remove the initial C<E<lt>> character so it is
+just an ordinary I<!> local command), see what guestfish commands it
+would run, and when you are happy with those prepend the C<E<lt>>
+character to run the guestfish commands for real.
+
 =head1 PIPES
 
 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the