fish: Allow -<<END as a syntax for uploading "heredocs".

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 13a9fa7..836c4f7 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


@@ -296,6 +296,27 @@ must be escaped with a backslash.
  command "/bin/echo 'foo      bar'"
  command "/bin/echo \'foo\'"
 
  command "/bin/echo 'foo      bar'"
  command "/bin/echo \'foo\'"
 

+=head1 NUMBERS
+
+Commands which take integers as parameters use the C convention which
+is to use C<0> to prefix an octal number or C<0x> to prefix a
+hexadecimal number.  For example:
+
+ 1234      decimal number 1234
+ 02322     octal number, equivalent to decimal 1234
+ 0x4d2     hexadecimal number, equivalent to decimal 1234
+
+When using the C<chmod> command, you almost always want to specify an
+octal number for the mode, and you must prefix it with C<0> (unlike
+the Unix L<chmod(1)> program):
+
+ chmod 0777 /public  # OK
+ chmod 777 /public   # WRONG! This is mode 777 decimal = 01411 octal.
+
+Commands that return numbers usually print them in decimal, but
+some commands print numbers in other radices (eg. C<umask> prints
+the mode in octal, preceeded by C<0>).
+

 =head1 WILDCARDS AND GLOBBING
 
 Neither guestfish nor the underlying guestfs API performs
 =head1 WILDCARDS AND GLOBBING
 
 Neither guestfish nor the underlying guestfs API performs


@@ -348,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>).
 
 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


@@ -363,6 +387,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


@@ -461,6 +486,39 @@ user ID of the process, and C<$PID> is the process ID of the server.
 
 Guestfish client and server versions must match exactly.
 
 
 Guestfish client and server versions must match exactly.
 

+=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.  You can also use a special "heredoc"-like syntax to read up to
+some arbitrary end marker:
+
+ upload -<<END /foo
+ input line 1
+ input line 2
+ input line 3
+ END
+
+Any string of characters can be used instead of C<END>.  The end
+marker must appear on a line of its own, without any preceeding or
+following characters (not even spaces).
+
+Note that the C<-E<lt>E<lt>> syntax only applies to parameters used to
+upload local files (so-called "FileIn" parameters in the generator).
+

 =head1 GUESTFISH COMMANDS
 
 The commands in this section are guestfish convenience commands, in
 =head1 GUESTFISH COMMANDS
 
 The commands in this section are guestfish convenience commands, in


@@ -719,11 +777,16 @@ I<1> if there was an error.
 L<guestfs(3)>,
 L<http://libguestfs.org/>,
 L<virt-cat(1)>,
 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