Dist::Z...Watcher(3)

💖 Dist::Z...Watcher 💖

okay bestie, so this is Dist::Zilla::Role::FileWatcher — it lives in the User Contributed Perl Documentation section, and it's literally the role that lets your plugin know when somebody messes with a file's contents. no cap, it's giving "I'm watching you" energy but make it wholesome 🫶

---

✨ NAME ✨

Dist::Zilla::Role::FileWatcher — Receive notification when something changes a file's contents 🔔👀

---

🌸 VERSION 🌸

version 0.006

---

🦋 SYNOPSIS 🦋

package Dist::Zilla::Plugin::MyPlugin;
use Moose;
with 'Dist::Zilla::Role::SomeRole', 'Dist::Zilla::Role::FileWatcher';

sub some_phase
{
    my $self = shift;

    my (file) = grep { $_->name eq 'some_name' } @{$self->zilla->files};
    # ... do something with this file ...

    $self->lock_file($file, 'KEEP OUT!');

    # or:

    $self->watch_file(
        $file,
        sub {
            my ($plugin, $file) = @_;
            ... do something with the file object ...
        },
    );
}

like, you just with the role and suddenly your plugin has ✨awareness✨. iconic.

---

💅 DESCRIPTION 💅

This is a role for Dist::Zilla plugins, and what it gives you is a whole mechanism for detecting files changing their content and acting on it. 🕵️‍♀️

when is that even useful, you ask? okay so picture this: your plugin does a thing based on a file's content (maybe it copies that content into another file, slay), and then LATER in the build process, that source file's content gets modified. without this role you'd just be standing there like 😭. with this role, you get notified. main character energy, fr fr.

---

👑 METHODS 👑

This role adds the following methods to your plugin class:

🌈 watch_file($file, $subref)

This method takes two arguments: the $file object you want to watch, and a subroutine that gets invoked when the file's contents change. 💖

It is called as a method on your plugin, and it is passed one additional argument: the $file object that changed. so your sub gets the plugin and the file, periodt.

🔥 lock_file($file, $message?)

This method takes the $file object to watch, plus an optional message string. when the file is modified after it's been locked, the build dies. 💀

that's the whole point bestie — it's a hard stop. 'KEEP OUT!' really means keep out.

---

🎀 SUPPORT 🎀

Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Role-FileWatcher> (or bug-Dist-Zilla-Role-FileWatcher@rt.cpan.org <mailto:bug-Dist-Zilla-Role-FileWatcher@rt.cpan.org>). 🙈

she's also usually active on irc, as 'ether' at irc.perl.org. come say hi 💜

---

🌟 SEE ALSO 🌟

• Dist::Zilla::Role::File::ChangeNotification — in this distribution, the underlying implementation for watching the file 👀
• Dist::Zilla::File::OnDisk
• Dist::Zilla::File::InMemory

---

💜 AUTHOR 💜

Karen Etheridge <ether@cpan.org> 👑

---

🍓 CONTRIBUTOR 🍓

Yanick Champoux <yanick@babyl.dyndns.org>

---

⭐ COPYRIGHT AND LICENSE ⭐

This software is copyright (c) 2013 by Karen Etheridge.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page bestie, no notes 💅 this was perl v5.42.0, dated 2025-07-25, filed under Dist::Z...Watcher(3) — mwah, go watch some files 🦋✨