X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfish.pod;h=d83a61ca5549042aa9372ebad11b7fa5f680b661;hp=8691dfe9dd7eeeb95b1ba5b9ed76008a69446c27;hb=da7cf3670fe60301beeb175ff6c284b737d5b7f4;hpb=d268e64fe76944dc042e7ec68a65e59a6cff16ce

diff --git a/guestfish.pod b/guestfish.pod
index 8691dfe..d83a61c 100644
--- a/guestfish.pod
+++ b/guestfish.pod
@@ -18,7 +18,7 @@ Create a new C</etc/motd> file in a guest:
  add disk.img
  run
  mount /dev/VolGroup00/LogVol00 /
- upload new_motd /etc/motd
+ write_file /etc/motd "Hello users" 0
  _EOF_
 
 List the LVs in a guest:
@@ -97,11 +97,23 @@ automatically launched.
 Disable autosync.  This is enabled by default.  See the discussion
 of autosync in the L<guestfs(3)> manpage.
 
+=item B<-r> | B<--ro>
+
+This changes the C<-m> option so that mounts are done read-only
+(see C<guestfs_mount_ro> in the L<guestfs(3)> manpage).
+
 =item B<-v> | B<--verbose>
 
 Enable very verbose messages.  This is particularly useful if you find
 a bug.
 
+=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.
+
 =back
 
 =head1 COMMANDS ON COMMAND LINE
@@ -156,6 +168,85 @@ The only exception is that if the C<-m> or C<--mount> option was
 given, the guest is automatically run for you (simply because
 guestfish can't mount the disks you asked for without doing this).
 
+=head1 QUOTING
+
+You can quote ordinary parameters using either single or double
+quotes.  For example:
+
+ add "file with a space.img"
+
+ rm '/file name'
+
+ rm '/"'
+
+A few commands require a list of strings to be passed.  For these, use
+a space-separated list, enclosed in quotes.  For example:
+
+ vgcreate VG "/dev/sda1 /dev/sdb1"
+
+=head1 WILDCARDS AND GLOBBING
+
+Neither guestfish nor the underlying guestfs API performs
+wildcard expansion (globbing) by default.  So for example the
+following will not do what you expect:
+
+ rm-rf /home/*
+
+Assuming you don't have a directory literally called C</home/*>
+then the above command will return an error.
+
+To perform wildcard expansion, use the C<glob> command.
+
+ glob rm-rf /home/*
+
+runs C<rm-rf> on each path that matches (ie. potentially running
+the command many times), equivalent to:
+
+ rm-rf /home/jim
+ rm-rf /home/joe
+ rm-rf /home/mary
+
+C<glob> only works on simple guest paths and not on device names.
+
+If you have several parameters, each containing a wildcard, then glob
+will perform a cartesian product.
+
+=head1 COMMENTS
+
+Any line which starts with a I<#> character is treated as a comment
+and ignored.  The I<#> can optionally be preceeded by whitespace,
+but B<not> by a command.  For example:
+
+ # this is a comment
+         # this is a comment
+ foo # NOT a comment
+
+Blank lines are also ignored.
+
+=head1 RUNNING COMMANDS LOCALLY
+
+Any line which starts with a I<!> character is treated as a command
+sent to the local shell (C</bin/sh> or whatever L<system(3)> uses).
+For example:
+
+ !mkdir local
+ tgz-out /remote local/remote-data.tar.gz
+
+will create a directory C<local> on the host, and then export
+the contents of C</remote> on the mounted filesystem to
+C<local/remote-data.tar.gz>.  (See C<tgz-out>).
+
+=head1 EXIT ON ERROR BEHAVIOUR
+
+By default, guestfish will ignore any errors when in interactive mode
+(ie. taking commands from a human over a tty), and will exit on the
+first error in non-interactive mode (scripts, commands given on the
+command line).
+
+If you prefix a command with a I<-> character, then that command will
+not cause guestfish to exit, even if that (one) command returns an
+error.
+
 =head1 COMMANDS
 
 =head2 help
@@ -201,6 +292,44 @@ number of 512 byte sectors
 
 =back
 
+=head2 echo
+
+ echo [params ...]
+
+This echos the parameters to the terminal.
+
+=head2 edit | vi | emacs
+
+ edit filename
+
+This is used to edit a file.  It downloads the file, edits it
+locally using your editor, then uploads the result.
+
+The editor is C<$EDITOR>.  However if you use the alternate
+commands C<vi> or C<emacs> you will get those corresponding
+editors.
+
+NOTE: This will not work reliably for large files
+(> 2 MB) or binary files containing \0 bytes.
+
+=head2 lcd
+
+ lcd directory
+
+Change the local directory, ie. the current directory of guestfish
+itself.
+
+Note that C<!cd> won't do what you might expect.
+
+=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.
+
 @ACTIONS@
 
 =head1 ENVIRONMENT VARIABLES
@@ -217,17 +346,37 @@ same effect as using the B<-v> option.
 Set the path that guestfish uses to search for kernel and initrd.img.
 See the discussion of paths in L<guestfs(3)>.
 
+=item LIBGUESTFS_QEMU
+
+Set the default qemu binary that libguestfs uses.  If not set, then
+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 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>.
+
 =back
 
+=head1 EXIT CODE
+
+guestfish returns I<0> if the commands completed without error, or
+I<1> if there was an error.
+
 =head1 SEE ALSO
 
 L<guestfs(3)>,
-L<http://et.redhat.com/~rjones/libguestfs>.
+L<http://libguestfs.org/>.
 
 =head1 AUTHORS
 
@@ -236,7 +385,7 @@ Richard W.M. Jones (C<rjones at redhat dot com>)
 =head1 COPYRIGHT
 
 Copyright (C) 2009 Red Hat Inc.
-L<http://et.redhat.com/~rjones/libguestfs>
+L<http://libguestfs.org/>
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by