watchfiles(1)

💖 watchfiles(1) 💖

okay so this is the manual page for watchfiles, which lives in the General Commands Manual section (section 1, bestie, the commands section, iykyk) 🫶

---

✨ NAME ✨

watchfiles — Simple, modern and high performance file watching 🔥

---

🌸 SYNOPSIS 🌸

watchfiles [--ignore-paths <IGNORE_PATHS>] [--target-type (command |
function | auto)] [--filter <FILTER>] [--args <ARGS>] [--verbose]
[--non-recursive] [--verbosity (warning | info | debug)]
[--sigint-timeout <SIGINT_TIMEOUT>] [--grace-period <GRACE_PERIOD>]
[--sigkill-timeout <SIGKILL_TIMEOUT>] [--ignore-permission-denied]
target [paths ...]

watchfiles (-h | --help)
watchfiles (-V | --version)

no cap, that first line is giving a lot, but it's just the full list of everything you can pass in one go 💅

---

🦋 DESCRIPTION 🦋

watchfiles watches one or more directories and executes either a Shell command or a Python function on file changes. that's the whole vibe. files change, stuff runs. iconic behaviour honestly ✨

---

🎀 ARGUMENTS 🎀

• target — Command or dotted function path to run. this is the thing that actually goes off when your files do something 👑
• paths — Filesystem paths to watch, defaults to current directory. leave it out and it just watches wherever you're standing 🫶

---

💅 OPTIONS 💅

• -h | --help — Show this help message and exit. classic. we love a help flag 💖
• --ignore-paths <IGNORE_PATHS> — Specify directories to ignore, to ignore multiple paths use a comma as separator, e.g. "env" or "env,node_modules". commas, bestie, not spaces 🍓
• --target-type (command | function | auto) — Whether the target should be intercepted as a shell command or a Python function, defaults to "auto" which infers the target type from the target string. auto is out here doing detective work 🔍
• --filter <FILTER> — Which files to watch, defaults to "default" which uses the DefaultFilter, "python" uses the PythonFilter, "all" uses no filter, any other value is interpreted as a Python function/class path which is imported. so "all" is the no-thoughts-just-vibes option 🌈
• --args <ARGS> — Arguments to set on sys.argv before calling target function, used only if the target is a function. note the only if — command targets don't get this 🙈
• --verbose — Set log level to "debug", wins over --verbose... no wait, wins over --verbosity. okay bestie, --verbose is the main character here, it beats --verbosity every single time 👑
• --non-recursive — Do not watch for changes in sub-directories recursively. it stays in its lane, respectfully 🦋
• --verbosity (warning | info | debug) — Log level, defaults to "info" ⭐
• --sigint-timeout <SIGINT_TIMEOUT> — How long to wait for the sigint timeout before sending sigkill. the escalation pipeline 😭
• --grace-period <GRACE_PERIOD> — Number of seconds after the process is started before watching for changes. give it a lil minute to get ready 🧚
• --sigkill-timeout <SIGKILL_TIMEOUT> — How long to wait for the sigkill timeout before issuing a timeout exception. yeah, if even that doesn't land, you get an exception 💀
• --ignore-permission-denied — Ignore permission denied errors while watching files and directories. the "i don't see it, i don't care" option, lowkey valid 🌸
• -V | --version — Show program's version number and exit 💜

okay real talk for a sec: --sigint-timeout and --sigkill-timeout are the ones where things get intense — signals are getting sent. read those two properly before you go wild, bestie 🫶

---

🔥 EXAMPLES 🔥

Watching the current directory and calling a Python function:

$ watchfiles foobar.main

Watching Python files in two local directories and calling a Shell command:

$ watchfiles --filter python 'pytest --lf' src tests

see how the second one is watching src and tests and only paying attention to python files? ate. 💅

---

😭 BUGS 😭

Bugs can be reported to your distribution's bug tracker or upstream at <https://github.com/samuelcolvin/watchfiles/issues>. pls be nice when you file them, the maintainers are people too 🥺

---

👑 AUTHOR 👑

Louis-Philippe Véronneau

---

aaaand that's the whole page bestie, 2024 edition of watchfiles(1) from the General Commands Manual — go watch some files, you're gonna slay 💖✨🎀