[DRE-commits] [rerun] 06/11: add a manpage

[Antonio Terceiro]

This is an automated email from the git hooks/post-receive script.

terceiro pushed a commit to branch master
in repository rerun.

commit 58fc3516e22cac3db74296026bbecb6ab6b9e37d
Author: Antonio Terceiro <terceiro at softwarelivre.org>
Date:   Sat Aug 8 12:22:14 2015 -0300

    add a manpage
---
 debian/clean          |   1 +
 debian/rerun.1.ronn   | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++
 debian/rerun.manpages |   1 +
 debian/rules          |   4 ++
 4 files changed, 132 insertions(+)

diff --git a/debian/clean b/debian/clean
new file mode 100644
index 0000000..f463b33
--- /dev/null
+++ b/debian/clean
@@ -0,0 +1 @@
+debian/rerun.1
diff --git a/debian/rerun.1.ronn b/debian/rerun.1.ronn
new file mode 100644
index 0000000..7e4c19a
--- /dev/null
+++ b/debian/rerun.1.ronn
@@ -0,0 +1,126 @@
+rerun(1) -- launches commands and restarts them on filesystem changes
+=====================================================================
+
+## USAGE
+
+rerun [options] [--] cmd
+
+## EXAMPLES
+
+For example, if you're running a Sinatra app whose main file is `app.rb`:
+
+        rerun ruby app.rb
+
+If the first part of the command is a `.rb` filename, then `ruby` is
+optional, so the above can also be accomplished like this:
+
+        rerun app.rb
+
+Rails doesn't automatically notice all config file changes, so you can force it
+to restart when you change a config file like this:
+
+        rerun --dir config rails s
+
+Or if you're using Thin to run a Rack app that's configured in config.ru
+but you want it on port 4000 and in debug mode, and only want to watch
+the `app` and `web` subdirectories:
+
+        rerun --dir app,web -- thin start --debug --port=4000 -R config.ru
+
+The `--` is to separate rerun options from cmd options. You can also
+use a quoted string for the command, e.g.
+
+        rerun --dir app "thin start --debug --port=4000 -R config.ru"
+
+Rackup can also be used to launch a Rack server, so let's try that:
+
+        rerun -- rackup --port 4000 config.ru
+
+Want to mimic [autotest](https://github.com/grosser/autotest)? Try
+
+        rerun -x rake
+
+or
+
+        rerun -cx rspec
+
+And if you're using [Spork](https://github.com/sporkrb/spork) with Rails, you
+need to [restart your spork server](https://github.com/sporkrb/spork/issues/201)
+whenever certain Rails environment files change, so why not put this in your
+Rakefile...
+
+    desc "run spork (via rerun)"
+    task :spork do
+      sh "rerun --pattern '{Gemfile,Gemfile.lock,spec/spec_helper.rb,.rspec,spec/factories/**,config/environment.rb,config/environments/test.rb,config/initializers/*.rb,lib/**/*.rb}' -- spork"
+    end
+
+and start using `rake spork` to launch your spork server?
+
+(If you're using Guard instead of Rerun, check out
+[guard-spork](https://github.com/guard/guard-spork)
+for a similar solution.)
+
+How about regenerating your HTML files after every change to your
+[Erector](http://erector.rubyforge.org) widgets?
+
+        rerun -x erector --to-html my_site.rb
+
+Use Heroku Cedar? `rerun` is now compatible with `foreman`. Run all your
+Procfile processes locally and restart them all when necessary.
+
+        rerun foreman start
+
+## OPTIONS
+
+`--dir` directory (or directories) to watch (default = "."). Separate multiple paths with ',' and/or use multiple `-d` options.
+
+`--pattern` glob to match inside directory. This uses the Ruby Dir glob style -- see <http://www.ruby-doc.org/core/classes/Dir.html#M002322> for details.
+By default it watches files ending in: `rb,js,css,coffee,scss,sass,erb,html,haml,ru,slim,md`.
+On top of this, it also ignores dotfiles, `.tmp` files, and some other files and directories (like `.git` and `log`).
+Run `rerun --help` to see the actual list.
+
+`--ignore pattern` file glob to ignore (can be set many times). To ignore a directory, you must append '/*' e.g.
+  `--ignore 'coverage/*'`.
+
+  *On top of --pattern and --ignore, we ignore any changes to files and dirs starting with a dot.*
+
+`--signal` (or -s) use specified signal (instead of the default SIGTERM) to terminate the previous process.
+This may be useful for forcing the respective process to terminate as quickly as possible.
+(`--signal KILL` is the equivalent of `kill -9`)
+
+`--clear` (or -c) clear the screen before each run
+
+`--exit` (or -x) expect the program to exit. With this option, rerun checks the return value; without it, rerun checks that the launched process is still running.
+
+`--background` (or -b) disable on-the-fly commands, allowing the process to be backgrounded
+
+`--no-growl` don't use growl
+
+`--name` set the app name (for display)
+
+Also `--version` and `--help`, naturally.
+
+## ON-THE-FLY COMMANDS
+
+While the app is (re)running, you can make things happen by pressing keys:
+
+* **r** -- restart (as if a file had changed)
+* **c** -- clear the screen
+* **x** or **q** -- exit (just like control-C)
+* **p** -- pause/unpause filesystem watching
+
+If you're backgrounding or using Pry or a debugger, you might not want these
+keys to be trapped, so use the `--background` option.
+
+## SIGNALS
+
+The current algorithm for killing the process is:
+
+* send [SIGTERM](http://en.wikipedia.org/wiki/SIGTERM) (or the value of the `--signal` option)
+* if that doesn't work after 4 seconds, send SIGINT (aka control-C)
+* if that doesn't work after 2 more seconds, send SIGKILL (aka kill -9)
+
+This seems like the most gentle and unixy way of doing things, but it does
+mean that if your program ignores SIGTERM, it takes an extra 4 to 6 seconds to
+restart.
+
diff --git a/debian/rerun.manpages b/debian/rerun.manpages
new file mode 100644
index 0000000..f463b33
--- /dev/null
+++ b/debian/rerun.manpages
@@ -0,0 +1 @@
+debian/rerun.1
diff --git a/debian/rules b/debian/rules
index 3454d59..b952698 100755
--- a/debian/rules
+++ b/debian/rules
@@ -4,3 +4,7 @@ export GEM2DEB_TEST_RUNNER = --check-dependencies
 
 %:
 	dh $@ --buildsystem=ruby --with ruby
+
+override_dh_auto_build:
+	dh_auto_build
+	ronn --roff debian/rerun.1.ronn

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-ruby-extras/rerun.git