New API: write for creating files with fixed content (RHBZ#501889).

[libguestfs.git] / fish / guestfish.pod

diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 165cdf2..274f1d4 100644 (file)
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -27,10 +27,11 @@ guestfish - the libguestfs Filesystem Interactive SHell
  Welcome to guestfish, the libguestfs filesystem interactive shell for
  editing virtual machine filesystems.
  
- Type: 'help' for help with commands
+ Type: 'help' for a list of commands
+       'man' to read the manual
        'quit' to quit the shell
  
- ><fs> help
+ ><fs> man
 
 =head2 From shell scripts
 
@@ -40,7 +41,7 @@ Create a new C</etc/motd> file in a guest:
  add disk.img
  run
  mount /dev/vg_guest/lv_root /
- write_file /etc/motd "Welcome, new users" 0
+ write /etc/motd "Welcome, new users"
  _EOF_
 
 List the LVM logical volumes in a guest:
@@ -56,7 +57,7 @@ Update C</etc/resolv.conf> in a guest:
 
  guestfish \
    add disk.img : run : mount /dev/vg_guest/lv_root / : \
-   write-file /etc/resolv.conf "nameserver 1.2.3.4" 0
+   write /etc/resolv.conf "nameserver 1.2.3.4"
 
 Edit C</boot/grub/grub.conf> interactively:
 
@@ -451,6 +452,39 @@ 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.  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 EXIT ON ERROR BEHAVIOUR
 
 By default, guestfish will ignore any errors when in interactive mode
@@ -517,7 +551,7 @@ multiple times (and can be mixed with I<-a>).
 
 The new disk is called C<test1.img> for the first I<-N>, C<test2.img>
 for the second and so on.  Existing files in the current directory are
-not overwritten, so you may need to do C<rm -f test1.img>.
+I<overwritten>.
 
 The type briefly describes how the disk should be sized, partitioned,
 how filesystem(s) should be created, and how content should be added.
@@ -552,39 +586,6 @@ Create a blank 200MB disk:
 
  guestfish -N disk:200M
 
-=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
@@ -679,6 +680,12 @@ itself.
 
 Note that C<!cd> won't do what you might expect.
 
+=head2 man | manual
+
+ man
+
+Opens the manual page for guestfish.
+
 =head2 more | less
 
  more filename
@@ -835,8 +842,8 @@ enough.
 
 =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
 
@@ -860,7 +867,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