Added options to isolate stdout or stderr only. Added documentation.
authorFlavio Poletti <flavio@polettix.it>
Thu, 11 Sep 2008 16:30:46 +0000 (11 18:30 +0200)
committerFlavio Poletti <flavio@polettix.it>
Thu, 11 Sep 2008 16:30:46 +0000 (11 18:30 +0200)
deploy

diff --git a/deploy b/deploy
index acc00a4..41ec7f6 100755 (executable)
--- a/deploy
+++ b/deploy
@@ -31,6 +31,8 @@ GetOptions(
      password|pass|p:s
      prompt|P!
      script|s=s
+     stderr|E!
+     stdout|O!
      username|user|u=s
      )
 );
@@ -41,6 +43,10 @@ pod2usage(-verbose => 99, -sections => 'USAGE|EXAMPLES|OPTIONS')
   if $config{help};
 pod2usage(-verbose => 2) if $config{man};
 
+pod2usage(-verbose => 99, -sections => 'USAGE',
+   message => 'Only one allowed between --stdout and --stderr')
+   if $config{stdout} && $config{stderr};
+
 # Script implementation here
 my @hostnames = @ARGV;
 @ARGV = ();
@@ -79,14 +85,23 @@ sub operate_on_host {
    $|++;
    print "$remote ";
    my ($out, $err, $exit) = $ssh->cmd($remote);
-   print "exit = $exit\n";
-   for ([STDOUT => $out], [STDERR => $err]) {
-      my ($type, $val) = @$_;
-      next unless defined $val;
-      $val =~ s{\s+\z}{}mxs;
-      $val =~ s{^}{$type  }gmxs;
-      print $val, "\n\n";
-   } ## end for ([STDOUT => $out], ...
+
+   if ($config{stdout} && defined $out) {
+      print {*STDOUT} $out;
+   }
+   elsif ($config{stderr} && defined $err) {
+      print {*STDOUT} $err;
+   }
+   else {
+      print "exit = $exit\n";
+      for ([STDOUT => $out], [STDERR => $err]) {
+         my ($type, $val) = @$_;
+         next unless defined $val;
+         $val =~ s{\s+\z}{}mxs;
+         $val =~ s{^}{$type }gmxs;
+         print $val, "\n\n";
+      } ## end for ([STDOUT => $out], ...
+   }
 
    return;
 } ## end sub operate_on_host
@@ -150,7 +165,8 @@ See version at beginning of script, variable $VERSION, or call
 
    deploy [--debug|-D] [--dir|--directory|-d <dirname>]
           [--password|--pass|-p] [--prompt|-P]
-          [--script|-s <scriptname>] [--username|--user|-u]
+          [--script|-s <scriptname>] [--stderr|-E] [--stdout|-O]
+          [--username|--user|-u]
 
 =head1 EXAMPLES
 
@@ -192,6 +208,70 @@ just hit enter when requested for a password, or you can pass
 C<-p> without a password on the command line (you can actually pass
 every password you can think of, it will be ignored).
 
+=head2 Output Format
+
+The normal output format is geared at easing parsing by other programs. It
+is compound of the following parts:
+
+=over
+
+=item *
+
+a single line specifing the hostname/ip, with the following format:
+
+   *** OPERATING ON <hostname> ***
+
+=item *
+
+a single line reporting the exit code from the remote process, with the
+following format:
+
+   </path/to/deployed/program> exit = <exit-code>
+
+=item *
+
+0 or more lines starting with C<STDOUT > (note the space);
+
+=item *
+
+0 or more lines starting with C<STDERR > (note the space).
+
+=back
+
+If any of L</--stderr> or L</--stdout> are present, then the relevant
+channel is printed on STDOUT immediately after the first line of the
+format above, unchanged.
+
+=head2 Example Runs
+
+Suppose to have the following script F<bar.sh> to deploy:
+
+   #!/bin/bash
+
+   echo 'Hi there!'
+   ls baz
+   echo 'How are you all?!?'
+
+If you don't provide any of L</--stderr> or L</--stdout>, you will have
+something like this:
+
+   *** OPERATING ON foo.example.com ***
+   /tmp/our-deploy/bar.sh exit = 0
+   STDOUT Hi there!
+   STDOUT How are you all?!?
+   STDERR ls: baz: No such file or directory
+
+If you pass L<--stderr> you will get:
+
+   *** OPERATING ON foo.example.com ***
+   ls: baz: No such file or directory
+
+If you pass L<--stdout> you will get:
+
+   *** OPERATING ON foo.example.com ***
+   Hi there!
+   How are you all?!?
+
 =head1 OPTIONS
 
 =over
@@ -260,6 +340,16 @@ script will be sanitised (only alphanumeric, C<_>, C<.> and C<-> will
 be retained), so be careful if you have to look for the uploaded
 script later.
 
+=item --stderr | -E
+
+select only the STDERR channel from the responses got via SSH. This
+option cannot be used with L</--stdout>.
+
+=item --stdout | -O
+
+select only the STDOUT channel from the responses got via SSH. This
+option cannot be used with L</--stderr>.
+
 =item --usage
 
 print a concise usage line and exit.