Rerun
=====

Command-line executable Python script to re-run the given command every time
files are modified in the current directory or its subdirectories.

Usage
=====

::

    rerun [--help|-h] [--verbose|-v] [--ignore|-i=<file>] [--version] <command>

Where::

    <command>           Command to execute as a single arg, i.e. spaces and
                        other special characters should be escaped, or else the
                        whole command should be put in quotes.
    --help|-h           Show this help message and exit.
    --ignore|-i=<file>  File or directory to ignore. Any directories of the
                        given name (and their subdirs) are excluded from the
                        search for changed files. Any modification to files of
                        the given name are ignored. The given value is
                        compared to basenames, so for example, "--ignore=def"
                        will skip the contents of directory "./abc/def/" and
                        will ignore file "./ghi/def". Can be specified multiple
                        times.
    --verbose|-v        Display the names of changed files before the command
                        output.
    --version           Show version number and exit.

Example:

    rerun --verbose --ignore=__pycache__ "ls | grep r"

This will run ls piped through grep whenever any file changes, apart from
those files in __pycache__ and its subdirectories.

Description
===========

Rerun detects changes to files by polling file modification times once per
second. It looks in the current directory and all its subdirectories. On
detecting any changes, it clears the terminal and reruns the given command.

It always ignores directories called .svn, .git, .hg, .bzr, build and dist.
Additions to this list can be given using --ignore.

It always ignores files ending with .pyc or .pyo. This isn't currently
user-overrideable.

e.g::

    rerun python -m unittest mypackage.mymodule

will rerun your tests every time you save your source code, but it won't
rerun the tests a second time when .pyo files get updated as a result of
executing the tests. Handy for seeing the new test results in another console
window after you hit 'save' in your editor, without having to change window
focus.

While polling sounds sub-optimal, I've yet to encounter a project large
enough that rerun's resource usage was even noticeable. (Plus, see discussion
of 'watchdog' below.)


Dependencies
============

Tested on MacOSX, Ubuntu, WindowsXP, Windows 7.

Tested on Python 2.6, 2.7 and 3.3.

Python 2.6 requires argparse to be installed -
see requirements_2.6.txt.

No other dependencies.

Hacking
=======

To run tests requires mock, tox. On Python 2.6 also requires unittest2. 
See requirements_dev.txt and requirements_dev_2.6.txt.

Install
=======

::

    pip install rerun

Known Problems
==============

See issues at https://bitbucket.org/tartley/rerun/issues


Alternatives
============

PyPI package 'watchdog' is a cross-platform library for handling file-system
events, which includes script 'watchmedo', which looks like a more serious and
heavy-duty version of 'Rerun'. However it doesn't work for my primary use
case, which is re-running tests when files are saved by Vim. This is due to the
way Vim writes to temporary files and then moves the temp file to overwrite
data atomically. Vim thus guaruntees that the user never loses data, but also
fails to generate the correct FS events that watchmedo is looking for.

https://pypi.python.org/pypi/watchdog

Thanks
======

The idea came from the Bash command 'watch', and inspiration for this
implementation came from an old blog post by Jeff Winkler, whos website
http://jeffwinkler.net seems to have now died.

Thanks to Bitbucket user sgourley for reporting, chasing up and even
offering to fix issue #1, an egregious bug in ignoring directories, before
I finally spotted the error. Thanks for the prods!


Changes
=======

1.0.19 Now expects commands to be a single arg (i.e. spaces etc should be
       escaped, or the whole command quoted) thus allowing rerun to work on
       composite commands, such as pipelines.

1.0.18 Now runs on Python 2.6, and is tested on Python 3.3.


Contact
=======

:Documentation & download:
    http://pypi.python.org/pypi/rerun/

:Souce code and issues:
    https://bitbucket.org/tartley/rerun

:Contact the author:
    Jonathan Hartley, email: tartley at domain tartley.com, Twitter: @tartley.

