Skip to content
Browse files

Improve documentation for 'run'

  • Loading branch information...
1 parent 179907c commit f48d0ce3be676f595dc21d2d00e92f068a0ad0ce @FooBarWidget FooBarWidget committed Dec 9, 2012
Showing with 18 additions and 23 deletions.
  1. +13 −9 README.md
  2. +5 −14 run
View
22 README.md
@@ -195,18 +195,22 @@ Runs the given command but only print its output (both STDOUT and STDERR) if its
### run
-Runs the given command in the following way:
+This tool allows running a command in various ways. Supported features:
- * stdin is redirected to /dev/null.
- * stdout and stderr are both printed to `run`'s stdout, and also to either a log file or to syslog.
- * It waits until the command has exited and returns with the same exit code.
- * All signals are forwarded to the command process.
+ * Running the command with a different name (`argv[0]` value). Specify `--program-name NAME` to use this feature.
+ * Sending a copy of the output to a log file. Specify `--log-file FILENAME` to use this feature. It will overwrite the log file by default; specify `--append` to append to the file instead.
+ * Sending a copy of the output to syslog. Specify `--syslog` to use this feature. `run` will use the command's program name as the syslog program name. `--program-name` is respected.
+ * Sending the output to [pv](http://www.ivarch.com/programs/pv.shtml). You can combine this with `--log-file` and `--syslog`.
+ * Printing the exit code of the command to a status file once the command exits. Specify `--status-file FILENAME` to use this feature.
+ * Holding a lock file while the command is running. If the lock file already exists, then `run` will abort with an error. Otherwise, it will create the lock file, write the command's PID to the file and delete the file after the command has finished.
+ * Sending an email after the command has finished. Specify `--email-to EMAILS` to use this feature. It should be a comma-separated list of addresses.
-The following features are also available:
+`run` always exhibits the following properties:
- * `--status-file`: a file for storing the exit code of the command. It is created before the command is run, but is empty initially.
- * `--lock-file`: `run` will abort with an error if the given lock file already exists. Otherwise, it will create the lock file, write its PID to it and delete the lock file after the command has finished.
- * `--email-to`: send an email to the given (comma-separated) addresses when the command has finished.
+ * It redirects stdin to /dev/null.
+ * It exits with the same exit code as the command, unlike bash which exits with the exit code of the last command in the pipeline.
+ * stdout and stderr are both combined into a single stream. If you specify `--log-file`, `--syslog` or `--pv` then both stdout and stderr will be redirected to the pipeline.
+ * All signals are forwarded to the command process.
### syslog-tee
View
19 run
@@ -69,17 +69,12 @@ def start
create_log_file
write_status_file('')
+ STDIN.reopen("/dev/null", "r")
+
if has_sink?
- if pipe_stderr_to_sink?
- main_process = spawn(main_command,
- :in => ["/dev/null", "r"],
- :out => :pipe,
- :err => :pipe)
- else
- main_process = spawn(main_command,
- :in => ["/dev/null", "r"],
- :out => :pipe)
- end
+ main_process = spawn(main_command,
+ :out => :pipe,
+ :err => :pipe)
sink_process = spawn_sink(main_process)
[:in, :out].each do |channel|
main_process[channel].close if main_process[channel]
@@ -216,10 +211,6 @@ def has_sink?
return OPTIONS[:syslog] || OPTIONS[:log_file] || OPTIONS[:pv]
end
-def pipe_stderr_to_sink?
- return !OPTIONS[:pv]
-end
-
def spawn_sink(main_process)
if OPTIONS[:syslog]
command = ["#{TOOLS_DIR}/syslog-tee", "-t", "#{program_name}[#{main_process[:pid]}]"]

0 comments on commit f48d0ce

Please sign in to comment.
Something went wrong with that request. Please try again.