=head2 As an interactive shell
$ guestfish
-
+
Welcome to guestfish, the libguestfs filesystem interactive shell for
editing virtual machine filesystems.
-
+
Type: 'help' for help with commands
'quit' to quit the shell
-
+
><fs> help
=head2 As a script interpreter
Add a block device or virtual machine image to the shell.
+=item B<-D> | B<--no-dest-paths>
+
+Don't tab-complete paths on the guest filesystem. It is useful to be
+able to hit the tab key to complete paths on the guest filesystem, but
+this causes extra "hidden" guestfs calls to be made, so this option is
+here to allow this feature to be disabled.
+
=item B<-f file> | B<--file file>
Read commands from C<file>. To write pure guestfish
Enable very verbose messages. This is particularly useful if you find
a bug.
-=item B<-D> | B<--no-dest-paths>
+=item B<-V> | B<--version>
-Don't tab-complete paths on the guest filesystem. It is useful to be
-able to hit the tab key to complete paths on the guest filesystem, but
-this causes extra "hidden" guestfs calls to be made, so this option is
-here to allow this feature to be disabled.
+Display the guestfish / libguestfs version number and exit.
+
+=item B<-x>
+
+Echo each command before executing it.
=back
the contents of C</remote> on the mounted filesystem to
C<local/remote-data.tar.gz>. (See C<tgz-out>).
+=head1 PIPES
+
+Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
+first command (a guestfish command) to the second command (any host
+command). For example:
+
+ cat /etc/passwd | awk -F: '$3 == 0 { print }'
+
+(where C<cat> is the guestfish cat command, but C<awk> is the host awk
+program). The above command would list all accounts in the guest
+filesystem which have UID 0, ie. root accounts including backdoors.
+Other examples:
+
+ hexdump /bin/ls | head
+ list-devices | tail -1
+
+The space before the pipe symbol is required, any space after the pipe
+symbol is optional. Everything after the pipe symbol is just passed
+straight to the host shell, so it can contain redirections, globs and
+anything else that makes sense on the host side.
+
+To use a literal argument which begins with a pipe symbol, you have
+to quote it, eg:
+
+ echo "|"
+
=head1 EXIT ON ERROR BEHAVIOUR
By default, guestfish will ignore any errors when in interactive mode
not cause guestfish to exit, even if that (one) command returns an
error.
-=head1 COMMANDS
-
-=head2 help
+=head1 GUESTFISH COMMANDS
- help
- help cmd
-
-Without any parameter, this lists all commands. With a C<cmd>
-parameter, this displays detailed help for a command.
-
-=head2 quit | exit
-
-This exits guestfish. You can also use C<^D> key.
+The commands in this section are guestfish convenience commands, in
+other words, they are not part of the L<guestfs(3)> API.
=head2 alloc | allocate
NOTE: This will not work reliably for large files
(> 2 MB) or binary files containing \0 bytes.
+=head2 glob
+
+ glob command args...
+
+Expand wildcards in any paths in the args list, and run C<command>
+repeatedly on each matching path.
+
+See section WILDCARDS AND GLOBBING.
+
+=head2 help
+
+ help
+ help cmd
+
+Without any parameter, this lists all commands. With a C<cmd>
+parameter, this displays detailed help for a command.
+
=head2 lcd
lcd directory
Note that C<!cd> won't do what you might expect.
-=head2 glob
+=head2 more | less
- glob command args...
+ more filename
-Expand wildcards in any paths in the args list, and run C<command>
-repeatedly on each matching path.
+ less filename
-See section WILDCARDS AND GLOBBING.
+This is used to view a file.
+
+The default viewer is C<$PAGER>. However if you use the alternate
+command C<less> you will get the C<less> command specifically.
+
+NOTE: This will not work reliably for large files
+(> 2 MB) or binary files containing \0 bytes.
+
+=head2 quit | exit
+
+This exits guestfish. You can also use C<^D> key.
+
+=head2 reopen
+
+ reopen
+
+Close and reopen the libguestfs handle. It is not necessary to use
+this normally, because the handle is closed properly when guestfish
+exits. However this is occasionally useful for testing.
+
+=head2 time
+
+ time command args...
+
+Run the command as usual, but print the elapsed time afterwards. This
+can be useful for benchmarking operations.
+
+=head1 COMMANDS
@ACTIONS@
=over 4
+=item EDITOR
+
+The C<edit> command uses C<$EDITOR> as the editor. If not
+set, it uses C<vi>.
+
+=item HOME
+
+If compiled with GNU readline support, then the command history
+is saved in C<$HOME/.guestfish>
+
+=item LIBGUESTFS_APPEND
+
+Pass additional options to the guest kernel.
+
=item LIBGUESTFS_DEBUG
Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This has the
same effect as using the B<-v> option.
+=item LIBGUESTFS_MEMSIZE
+
+Set the memory allocated to the qemu process, in megabytes. For
+example:
+
+ LIBGUESTFS_MEMSIZE=700
+
=item LIBGUESTFS_PATH
Set the path that guestfish uses to search for kernel and initrd.img.
the qemu which was found at compile time by the configure script is
used.
-=item LIBGUESTFS_APPEND
-
-Pass additional options to the guest kernel.
+=item PAGER
-=item HOME
-
-If compiled with GNU readline support, then the command history
-is saved in C<$HOME/.guestfish>
-
-=item EDITOR
-
-The C<edit> command uses C<$EDITOR> as the editor. If not
-set, it uses C<vi>.
+The C<more> command uses C<$PAGER> as the pager. If not
+set, it uses C<more>.
=back