Japanese transliteration for "watch"
Miru is a script that watches directories for changes. When specific changes take place, it runs scripts or commands you specify.
For example, you could watch your Downloads folder and then automatically remove image metadata.
The current version is: 1.1.0
(This is biased towards UNIX machines. If you're on Windows, look up the appropriate alternatives to the commands in steps 3, 6, and 7)
Download the source files
Extract and move the
Miru-main/folder to a permanent location, like
Navigate to the
Miru-main/folder in your terminal, then run
chmod +x Miru.py(you will need to give your shell scripts executable permission likewise)
While staying in the terminal, run the following commands:
pip install watchdog(for watching directories)
pip install rich(for colorful formatting)
Double-check the shebang at line 1 of
Miru.pyto accurately reflect the location of your Python installation. Default is
.zshrc) file and add:
Reconfigure your shell by quitting terminal or running
miru --createto create an example configuration file (
.miruconf) in your home folder.
Note: If you don't want to deal with the config file, for whatever reason, you can invoke Miru with the necessary information with the
-cl flag, like so:
miru -cl any:::/path/:::command
Miru watches directories for certain events. Currently, it supports
miru without any arguments will start the Watcher. Also note that Miru only cares about the few specified arguments, and will not notice any others. Therefore,
miru sheep does the same thing as
miru --wabberjack and simply
Miru Config Syntax
#is a comment in a
- Newlines (AKA empty lines) are allowed.
The basic syntax for a config line is (without square brackets):
Every part of this line is mandatory.
In practice, this is an example:
For most use cases, you'll probably want to create a bash script (
.sh) instead of directly using a command. That way, you can also pass the changed file as an argument to your script, so your tasks don't become too expensive.
Note: Make sure your script/command can be invoked multiple times without consequence. If you watch for the
modified event, your script will be invoked multiple times (for each file, sometimes twice depending on your system, and the parent folder).
||Reset and/or Delete the
||Easily edit the
||Print the contents of the
||Passes the changed file or directory as a command line argument to the script you provided|
||Enable log output to a
||Do a recursive walk of the filesystem for every change. You'd better know what you're doing.|
||Ignore the .miruconf file and instead take the line directly as the third argument. This would look like:
||Show this menu and exit.|
You can pass multiple special arguments in one go. For example, if you want to log, pass the arguments, and do a recursive walk all at once, you can invoke Miru with
miru --log --pass --recursive or
miru -l -p -re
Q: Can I run multiple Watcher instances at a time?
Yes. So far, no bugs have been encountered. To do this, simply add more than one config line in the
.miruconf file. If you encounter any issues with multiple Watcher processes, please open an issue.
Q: Why does it not run as a daemon?
It is preferred to have some sort of feedback. If you run it normally via a terminal, it'll output the files you watch, when they change, and when commands or scripts are invoked.
Obviously, if you don't want to see the output or have a terminal window open, you could add it as a startup application or a
Q: How do I let my scripts know what files change?
- Either manually check the modification date of the files yourself; or
- Invoke miru with the
--passflag, to pass the changed file as a command line argument.
Use Ctrl+C to stop the Watcher (A 1-2 second (or long) delay is expected.)
This project uses Watchdog to watch the underlying filesystem for changes. Miru is simply a complex wrapper to allow you to easily modify these settings on-the-fly, without modifying some source code. It also allows for more advanced features like logging to a file.
Watchdog is released under the Apache v2 license. No modifications to the source code was made.