Watchdog 🐶

Watchdog is like 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.

Useful links

• Documentation
• Hex

Installation

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

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:

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:

# 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 Ctrl+\.

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:

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.