How to run something automatically when a file appears in a folder

What this is good for

A folder that things arrive in, and a job that should happen to each of them:

• Scans land in Inbox, get renamed by date and filed by type.
• A camera card is copied in; every photo gets converted and catalogued.
• A colleague drops a CSV on a share; it gets validated and imported.
• Anything saved to Screenshots gets compressed.
• A build output appears; it gets signed and copied to a staging area.

The pattern is always the same, and it is worth ten minutes because it removes a decision as well as a task.

The three ways it goes wrong

It fires on a file that is still being written. This is the big one. A file appears in a directory listing the moment it is created, not when it is complete. A 200 MB video copied over the network exists as a name for two minutes before it exists as a video. Process it at second one and you get a truncated file and a mysterious, intermittent failure.

The fix: wait for the size and modification time to stop changing — two identical readings a couple of seconds apart — before acting. Some workflows can do better and wait for a companion .done file, but the stability check works everywhere.

It fires twice. Watching APIs report a write, a metadata update, and a close as separate events. Poll, or debounce, or record what you have already handled — but do not assume one arrival means one event.

It runs forever. The action writes its output into the folder it is watching, which triggers the action, which writes another file. Write output somewhere else, or exclude the output pattern explicitly.

Polling versus watching

The operating systems offer notification APIs — ReadDirectoryChangesW, FSEvents, inotify. They are efficient and they have edge cases: they miss events under load, they behave differently on network shares, they lose track when a directory is replaced rather than modified.

Polling — list the directory every couple of seconds and compare — is unfashionable and much harder to break. For a folder that gets a handful of files an hour, the cost is nothing measurable, and it works identically on a local disk, an SMB share and a mounted phone.

For this class of automation, polling is usually the right answer.

Dry run first, always

An automation that moves files is a program you are going to leave running unattended. Before that, it should be able to tell you what it would do to the files currently sitting there, without doing it.

That catches the rule that matches more than you meant, the destination path with a typo, and the ordering problem where two rules both claim the same file. Once it is running unattended, those become surprises.

Keep a log too. When somebody asks why a file ended up where it did, the answer should be a line in a file rather than a reconstruction.

The programs for this

• MacroDeck is the simple one: watch a folder, run a command when a matching file appears, with {file} substituted for the path. --ext narrows it by extension, --run-existing catches up on what is already there, and --once does a single pass and exits — which makes it easy to test a rule, and easy to drive from cron or Task Scheduler instead of leaving a daemon up.
• DeskAutomate watches by polling and fires rules when a file appears or changes, and every action is a dry run unless you pass --apply.
• ActionForge runs many rules from one config file concurrently, each failing on its own, so one broken rule does not stop the other nine. validate checks the config before you run it.
• QuickFlow is for shared routines rather than triggers: a library of parameterised workflows a colleague can run correctly without reading them first, with a ledger of what ran.

Free while we are in preview, one file each, Windows and Mac.

Start it the boring way

Get the rule right by hand first. Run the single-pass mode over the files already in the folder and check the result. Then run it on a schedule — Task Scheduler on Windows, launchd or cron on macOS — before you consider a long-running watcher.

Scheduled beats resident for almost every folder that receives a few files an hour. It restarts cleanly, it cannot leak, and if it dies nobody has to notice.