# Watchdog 🐶
Watchdog is like [Guard](https://github.com/guard/guard), but written in Elixir.

It tries to make it easy to run tasks when file system events happen and it's
internal pipeline is based on [Plug](https://github.com/elixir-lang/plug).

## Useful links
- [Documentation](https://hexdocs.pm/watchdog)
- [Hex](https://hex.pm/packages/watchdog)

## Installation
The package can be installed by adding `watchdog` to your list of dependencies
in `mix.exs`:

``` elixir
def deps do
  [{:watchdog, "~> 0.1.0", only: [:dev, :test]}]
end
```

## Setting up
Installing Watchdog is easy, there are 2 simple steps (assuming you've added it
to `mix.exs` already).

### Create a pipeline
Watchdog works with a pipeline. Similar to how Plug creates pipelines. An
example pipeline might look like this:

``` elixir
defmodule MyApp.WatchdogPipeline do
  use Watchdog.Pipeline

  plug Watchdog.Integrations.Logger
  plug Watchdog.Integrations.ExUnit,
    args: ~w(test --exclude not_implemented)
end
```

### Configuring Watchdog
For Watchdog to know which pipeline to use, you must configure it. You can do so
like this:

``` elixir
# config/dev.exs
config :watchdog,
  pipeline: MyApp.WatchdogPipeline
```

That's all. Now you can run `mix watchdog` from your project to start the
watcher, and stop it with <kbd>Ctrl</kbd>+<kbd>\</kbd>.

## Building your own plug
Creating your own plug is easy, just have a look in `lib/watchdog/integrations`
for instance, if you want a plug that just logs every change, you can do that
like this:

``` elixir
defmodule Watchdog.Integrations.Logger do
  use Watchdog.Plug

  require Logger

  def call(%FileSystemEvent{file_path: file_path} = fs_event, _opts) do
    Logger.info("Observed a change in #{file_path}")

    {:next, fs_event}
  end
end
```

## Contributing
We welcome everyone to contribute to Watchdog and help us tackle existing
issues! To do so, there are a few things you need to know about the code.

The basic inner workings are as follows:

- `Watchdog.Watcher` starts, subscribes to `Sentix` for file system events,
  sends a `Watchdog.FileSystemEvent` to the runner.
- `Watchdog.Runner` receives the `FileSystemEvent` struct and executes the
  configured pipeline and sends the event through it.
- `Watchdog.Pipeline` contains logic for adding plugs, and executing it, which
  walks by each plug and continues if it responds with `{:next, fs_event}`.

If you want to publish your own Watchdog plug, we suggest naming it `watchdog-*`
so it's easier to find. So a plug for ExUnit would be named `watchdog-exunit`.

## License
Watchdog's source code is licensed under the MIT license.