X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=fish%2Fguestfish.pod;h=6477647b81049411d09e20a9b00279d8d853da19;hb=e3cca343f28fd1b837b5f746e53a5f4ab5b286cb;hp=e2ea5057d61e87cba52d21ac23265bba1cb6fcda;hpb=9ac3cfd1a7b9d5464cfd059328b547a31fb549a0;p=libguestfs.git

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index e2ea505..6477647 100644
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -18,6 +18,13 @@ guestfish - the libguestfs Filesystem Interactive SHell
 
  guestfish -i disk.img [disk.img ...]
 
+=head1 WARNING
+
+Using guestfish in read/write mode on live virtual machines can be
+dangerous, potentially causing disk corruption.  Use the I<--ro>
+(read-only) option to use guestfish safely if the disk image or
+virtual machine might be live.
+
 =head1 EXAMPLES
 
 =head2 As an interactive shell
@@ -101,11 +108,6 @@ shell scripts or the command line or interactively.  If you want to
 rescue a broken virtual machine image, you should look at the
 L<virt-rescue(1)> command.
 
-Using guestfish in read/write mode on live virtual machines can be
-dangerous, potentially causing disk corruption.  Use the I<--ro>
-(read-only) option to use guestfish safely if the disk image or
-virtual machine might be live.
-
 =head1 OPTIONS
 
 =over 4
@@ -168,7 +170,7 @@ See also: L<virt-inspector(1)>.
 =item B<--listen>
 
 Fork into the background and listen for remote commands.  See section
-I<REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
+L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 
 =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
 
@@ -178,7 +180,7 @@ If the mountpoint is omitted, it defaults to C</>.
 
 You have to mount something on C</> before most commands will work.
 
-If any C<-m> or C<--mount> options are given, the guest is
+If any I<-m> or I<--mount> options are given, the guest is
 automatically launched.
 
 If you don't know what filesystems a disk image contains, you
@@ -194,11 +196,11 @@ of autosync in the L<guestfs(3)> manpage.
 =item B<--remote[=pid]>
 
 Send remote commands to C<$GUESTFISH_PID> or C<pid>.  See section
-I<REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
+L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 
 =item B<-r> | B<--ro>
 
-This changes the C<-a> and C<-m> options so that disks are added and
+This changes the I<-a> and I<-m> options so that disks are added and
 mounts are done read-only (see L<guestfs(3)/guestfs_mount_ro>).
 
 The option must always be used if the disk image or virtual machine
@@ -272,7 +274,7 @@ any other commands
 C<run> is a synonym for C<launch>.  You must C<launch> (or C<run>)
 your guest before mounting or performing any other commands.
 
-The only exception is that if the C<-m> or C<--mount> option was
+The only exception is that if the I<-m> or I<--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).
 
@@ -367,6 +369,9 @@ 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>).
 
+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.
+
 =head1 PIPES
 
 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the
@@ -382,6 +387,7 @@ Other examples:
 
  hexdump /bin/ls | head
  list-devices | tail -1
+ tgz-out / - | tar ztf -
 
 The space before the pipe symbol is required, any space after the pipe
 symbol is optional.  Everything after the pipe symbol is just passed
@@ -424,6 +430,25 @@ This syntax implicitly calls C<case-sensitive-path> (q.v.) so it also
 handles case insensitivity like Windows would.  This only works in
 argument positions that expect a path.
 
+=head1 UPLOADING AND DOWNLOADING FILES
+
+For commands such as C<upload>, C<download>, C<tar-in>, C<tar-out> and
+others which upload from or download to a local file, you can use the
+special filename C<-> to mean "from stdin" or "to stdout".  For example:
+
+ upload - /foo
+
+reads stdin and creates from that a file C</foo> in the disk image,
+and:
+
+ tar-out /etc - | tar tf -
+
+writes the tarball to stdout and then pipes that into the external
+"tar" command (see L</PIPES>).
+
+When using C<-> to read from stdin, the input is read up to the end of
+stdin.
+
 =head1 EXIT ON ERROR BEHAVIOUR
 
 By default, guestfish will ignore any errors when in interactive mode
@@ -455,13 +480,13 @@ To cause the server to exit, send it the exit command:
  guestfish --remote exit
 
 Note that the server will normally exit if there is an error in a
-command.  You can change this in the usual way.  See section I<EXIT ON
-ERROR BEHAVIOUR>.
+command.  You can change this in the usual way.  See section
+L</EXIT ON ERROR BEHAVIOUR>.
 
 =head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES
 
 The C<eval> statement sets the environment variable C<$GUESTFISH_PID>,
-which is how the C<--remote> option knows where to send the commands.
+which is how the I<--remote> option knows where to send the commands.
 You can have several guestfish listener processes running using:
 
  eval `guestfish --listen`
@@ -660,6 +685,11 @@ can be useful for benchmarking operations.
 
 @ACTIONS@
 
+=head1 EXIT CODE
+
+guestfish returns 0 if the commands completed without error, or
+1 if there was an error.
+
 =head1 ENVIRONMENT VARIABLES
 
 =over 4
@@ -672,13 +702,13 @@ set, it uses C<vi>.
 =item GUESTFISH_PID
 
 Used with the I<--remote> option to specify the remote guestfish
-process to control.  See section I<REMOTE CONTROL GUESTFISH OVER A
-SOCKET>.
+process to control.  See section
+L</REMOTE CONTROL GUESTFISH OVER A SOCKET>.
 
 =item HOME
 
-If compiled with GNU readline support, then the command history
-is saved in C<$HOME/.guestfish>
+If compiled with GNU readline support, various files in the
+home directory can be used.  See L</FILES>.
 
 =item LIBGUESTFS_APPEND
 
@@ -728,10 +758,46 @@ enough.
 
 =back
 
-=head1 EXIT CODE
+=head1 FILES
+
+=over 4
+
+=item $HOME/.guestfish
+
+If compiled with GNU readline support, then the command history
+is saved in this file.
+
+=item $HOME/.inputrc
+
+=item /etc/inputrc
+
+If compiled with GNU readline support, then these files can be used to
+configure readline.  For further information, please see
+L<readline(3)/INITIALIZATION FILE>.
+
+To write rules which only apply to guestfish, use:
+
+ $if guestfish
+ ...
+ $endif
+
+Variables that you can set in inputrc that change the behaviour
+of guestfish in useful ways include:
+
+=over 4
+
+=item completion-ignore-case (default: on)
+
+By default, guestfish will ignore case when tab-completing
+paths on the disk.  Use:
 
-guestfish returns I<0> if the commands completed without error, or
-I<1> if there was an error.
+ set completion-ignore-case off
+
+to make guestfish case sensitive.
+
+=back
+
+=back
 
 =head1 SEE ALSO
 
@@ -745,6 +811,7 @@ L<virt-list-partitions(1)>,
 L<virt-ls(1)>,
 L<virt-make-fs(1)>,
 L<virt-rescue(1)>,
+L<virt-resize(1)>,
 L<virt-tar(1)>,
 L<virt-win-reg(1)>.
 
@@ -754,7 +821,7 @@ Richard W.M. Jones (C<rjones at redhat dot com>)
 
 =head1 COPYRIGHT
 
-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009-2010 Red Hat Inc.
 L<http://libguestfs.org/>
 
 This program is free software; you can redistribute it and/or modify