contrib: Add header to README file.

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 1364545..65fccc8 100644 (file)
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -98,7 +98,7 @@ the functionality of the guestfs API, see L<guestfs(3)>.
 
 Guestfish gives you structured access to the libguestfs API, from
 shell scripts or the command line or interactively.  If you want to
 
 Guestfish gives you structured access to the libguestfs API, from
 shell scripts or the command line or interactively.  If you want to

-rescue a broken virtual machine image, you might want to look at the
+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
 L<virt-rescue(1)> command.
 
 Using guestfish in read/write mode on live virtual machines can be


@@ -168,7 +168,7 @@ See also: L<virt-inspector(1)>.
 =item B<--listen>
 
 Fork into the background and listen for remote commands.  See section
 =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]>
 
 
 =item B<-m dev[:mountpoint]> | B<--mount dev[:mountpoint]>
 


@@ -178,7 +178,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


@@ -194,11 +194,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
 =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>
 
 
 =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 +272,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).
 


@@ -367,6 +367,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>).
 
 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
 =head1 PIPES
 
 Use C<command E<lt>spaceE<gt> | command> to pipe the output of the


@@ -382,6 +385,7 @@ Other examples:
 
  hexdump /bin/ls | head
  list-devices | tail -1
 
  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
 
 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 +428,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


@@ -455,13 +478,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
  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>,
 
 =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`


@@ -672,8 +695,8 @@ set, it uses C<vi>.
 =item GUESTFISH_PID
 
 Used with the I<--remote> option to specify the remote guestfish
 =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
 
 
 =item HOME
 


@@ -730,19 +753,24 @@ enough.
 
 =head1 EXIT CODE
 
 
 =head1 EXIT CODE
 

-guestfish returns I<0> if the commands completed without error, or
-I<1> if there was an error.
+guestfish returns 0 if the commands completed without error, or
+1 if there was an error.

 
 =head1 SEE ALSO
 
 L<guestfs(3)>,
 L<http://libguestfs.org/>,
 L<virt-cat(1)>,
 
 =head1 SEE ALSO
 
 L<guestfs(3)>,
 L<http://libguestfs.org/>,
 L<virt-cat(1)>,

+L<virt-df(1)>,

 L<virt-edit(1)>,
 L<virt-list-filesystems(1)>,
 L<virt-edit(1)>,
 L<virt-list-filesystems(1)>,

+L<virt-list-partitions(1)>,

 L<virt-ls(1)>,
 L<virt-ls(1)>,

+L<virt-make-fs(1)>,

 L<virt-rescue(1)>,
 L<virt-rescue(1)>,

-L<virt-tar(1)>.
+L<virt-resize(1)>,
+L<virt-tar(1)>,
+L<virt-win-reg(1)>.

 
 =head1 AUTHORS
 
 
 =head1 AUTHORS
 


@@ -750,7 +778,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