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 6f27245..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 ...]
 
 
  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
 =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.
 
 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
 =head1 OPTIONS
 
 =over 4


@@ -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.
 
 
 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
 automatically launched.
 
 If you don't know what filesystems a disk image contains, you


@@ -198,7 +200,7 @@ L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 
 =item B<-r> | B<--ro>
 
 
 =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
 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.
 
 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).
 
 given, the guest is automatically run for you (simply because
 guestfish can't mount the disks you asked for without doing this).
 


@@ -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.
 
 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
 =head1 EXIT ON ERROR BEHAVIOUR
 
 By default, guestfish will ignore any errors when in interactive mode


@@ -465,7 +486,7 @@ L</EXIT ON ERROR BEHAVIOUR>.
 =head2 CONTROLLING MULTIPLE GUESTFISH PROCESSES
 
 The C<eval> statement sets the environment variable C<$GUESTFISH_PID>,
 =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`
 You can have several guestfish listener processes running using:
 
  eval `guestfish --listen`


@@ -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.
 
 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...
 =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.
 
 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 quit | exit
 
 This exits guestfish.  You can also use C<^D> key.


@@ -664,6 +679,11 @@ can be useful for benchmarking operations.
 
 @ACTIONS@
 
 
 @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
 =head1 ENVIRONMENT VARIABLES
 
 =over 4


@@ -681,8 +701,8 @@ L</REMOTE CONTROL GUESTFISH OVER A SOCKET>.
 
 =item HOME
 
 
 =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
 
 
 =item LIBGUESTFS_APPEND
 


@@ -732,10 +752,46 @@ enough.
 
 =back
 
 
 =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
 
 
 =head1 SEE ALSO
 


@@ -759,7 +815,7 @@ Richard W.M. Jones (C<rjones at redhat dot com>)
 
 =head1 COPYRIGHT
 
 
 =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
 L<http://libguestfs.org/>
 
 This program is free software; you can redistribute it and/or modify