fish: In guestfish(1) turn command references into links.

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index c2154af..8fc720e 100644 (file)
--- 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
@@ -428,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
@@ -549,9 +570,6 @@ 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 glob
 
  glob command args...
@@ -589,9 +607,6 @@ 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.
@@ -664,6 +679,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
@@ -681,8 +701,8 @@ 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
 
@@ -732,10 +752,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
 
-guestfish returns I<0> if the commands completed without error, or
-I<1> if there was an error.
+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:
+
+ set completion-ignore-case off
+
+to make guestfish case sensitive.
+
+=back
+
+=back
 
 =head1 SEE ALSO
 
@@ -759,7 +815,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