A simple file watcher that automatically moves files into folders based on rules you define.
- Watch any directory for new files (defaults to Downloads)
- Move files based on glob patterns — extensions, names, catch-alls
- Never loses a file: an existing file at the destination is kept (renamed, skipped or replaced, your choice)
- Waits for downloads to finish, and ignores browsers' partial files (
*.part,*.crdownload, ...) - Cheap when idle: no polling unless you ask for it, no wake-ups while nothing changes
- Picks up config changes without a restart
- Recursive watching with configurable depth
- Cross-platform (Windows, macOS, Linux)
Download the appropriate binary for your OS from the Releases page, extract it, and run the executable. These binaries can update themselves.
Add rocas to your flake inputs and import the module:
# flake.nix
inputs.rocas.url = "github:chikof/rocas";Then in your NixOS configuration:
{ inputs, ... }: {
imports = [ inputs.rocas.nixosModules.default ];
services.rocas = {
enable = true;
watcher.watchPath = "/home/chiko/Downloads";
rules = [
{ patterns = [ "*.pdf" ]; destination = "/home/chiko/Documents"; }
{ patterns = [ "*.jpg" "*.png" ]; destination = "/home/chiko/Pictures"; }
];
};
}rocas will run as a system service under a dedicated rocas user. You can override this with services.rocas.user and services.rocas.group. The generated config is installed at /etc/rocas/rocas.toml and the log file lives in /var/lib/rocas.
Prefer this for per-user installs or if you want rocas to autostart on graphical login.
# flake.nix
inputs.rocas.url = "github:chikof/rocas";{ inputs, ... }: {
imports = [ inputs.rocas.homeManagerModules.default ];
programs.rocas = {
enable = true;
autostart = true;
rules = [
{ patterns = [ "*.pdf" ]; destination = "~/Documents"; }
{ patterns = [ "*.jpg" "*.png" ]; destination = "~/Pictures"; }
];
};
}When autostart is enabled, rocas runs as a systemd user service tied to your graphical session. You can manage it manually with:
systemctl --user status rocas
systemctl --user restart rocasEvery option maps to the key of the same name in the configuration below, in camelCase (watcher.settleMs is settle_ms).
| Option | Default | Description |
|---|---|---|
watcher.watchPath |
null |
Primary directory to watch; null is your Downloads directory (NixOS module: /home/<user>/Downloads) |
watcher.watchPaths |
[] |
Watch multiple directories simultaneously (takes precedence over watchPath) |
watcher.recursive |
true |
Watch subdirectories |
watcher.maxDepth |
null |
Max recursion depth (null = unlimited) |
watcher.poll |
false |
Poll instead of using OS notifications (network drives) |
watcher.intervalMillis |
1000 |
Polling interval (ms); only used when poll is true |
watcher.debounceMs |
50 |
Collapse rapid events for the same path within this window (ms) |
watcher.renameTimeoutMs |
50 |
Wait this long for a rename pair before treating the source as a delete |
watcher.settleMs |
1000 |
Move a file once its size and mtime have been unchanged this long (ms) |
watcher.maxWaitSecs |
300 |
Move a file anyway after waiting this long for it to settle (s) |
watcher.ignore |
null |
Filename globs never moved; null keeps the built-in list, a list replaces it |
watcher.scanOnStart |
false |
Organize files already present at startup |
misc.onConflict |
"rename" |
rename, skip or overwrite when the destination already has that name |
misc.reload |
true |
Reload the config when it changes |
misc.logLevel |
"info" |
trace debug info warn error |
misc.logFile |
null |
Path to the log file; null is the default path (NixOS module: /var/lib/rocas/rocas.log) |
misc.logMaxSizeMb |
10 |
Rotate the log file when it exceeds this size (MB); 0 disables rotation |
misc.logKeepFiles |
3 |
Number of rotated log files to keep |
rules |
[] |
List of { patterns, destination } rules |
misc.checkForUpdatesandmisc.autoUpdateare accepted for config compatibility but have no effect in Nix-managed installs: the package is built without self-update. Update rocas vianix flake updateinstead.
Rocas looks for its config file in the following locations depending on your OS:
- Linux:
~/.config/rocas/rocas.toml - macOS:
~/Library/Application Support/rocas/rocas.toml - Windows:
%APPDATA%\rocas\rocas.toml
The config file is optional: if it does not exist, rocas starts with the defaults below (watching your Downloads directory, no rules).
[watcher]
watch_path = "/home/chiko/Downloads" # directory to watch (single); omit for your Downloads directory
# watch_paths = ["/home/chiko/Downloads", "/home/chiko/Desktop"] # watch multiple dirs simultaneously
recursive = true # watch subdirectories
max_depth = 1 # max recursion depth: 0 = root only, 1 = root + one level, omit for unlimited
# poll = false # poll instead of using OS notifications (network drives)
# interval_millis = 1000 # polling interval (ms); only used when poll = true
# debounce_ms = 50 # collapse events within this window (ms); increase for slow/network drives
# rename_timeout_ms = 50 # wait this long for a rename pair before treating From as a delete (ms)
# settle_ms = 1000 # move a file once its size and mtime are unchanged this long (ms)
# max_wait_secs = 300 # move a file anyway after this long (s), with a warning
# ignore = ["*.part", "*.crdownload"] # filename globs never moved; replaces the built-in list
# scan_on_start = false # organize files already present at startup
[misc]
log_level = "info" # trace | debug | info | warn | error
on_conflict = "rename" # rename | skip | overwrite: when the destination already has that name
# reload = true # reload this file when it changes
# log_file = "/var/log/rocas/rocas.log" # omit for the default path (next to this file)
# log_max_size_mb = 10 # rotate when file exceeds this size (MB); 0 = no rotation
# log_keep_files = 3 # number of rotated files to keep
check_for_updates = true # check for updates on startup (builds with self-update only)
auto_update = false # install updates automatically (builds with self-update only)
[[rules]]
patterns = ["*.pdf", "*.docx"]
destination = "/home/chiko/Documents"
[[rules]]
patterns = ["*.jpg", "*.png", "*.gif"]
destination = "/home/chiko/Pictures"
[[rules]]
patterns = ["*"] # catch-all, matches anything not covered above
destination = "/home/chiko/Other"The first rule whose pattern matches a file wins. A pattern without / is matched against the file name, a pattern with / against the whole path.
- Settling. A new file is moved only once its size and modification time have not changed for
settle_ms(1 second by default), so a download that is still being written is left alone. If a file keeps changing, rocas moves it anyway aftermax_wait_secs(5 minutes) and logs a warning. Waiting never blocks other files or the watcher. - Ignored files. Names matching
ignoreare never moved. The built-in list covers partial downloads and lock files:*.part,*.crdownload,*.download,*.partial,*.tmp,*.opdownloadand.~lock.*. Settingignorereplaces the whole list. A browser's finished file is moved after it renames the download to its final name. - Conflicts. rocas never overwrites a file by default. When the destination already has a file with that name,
on_conflictdecides:renamekeeps both and names the incoming filename (1).ext,name (2).ext, and so on;skipleaves the incoming file where it is and logs it;overwritereplaces the existing file. - Destinations inside a watched directory. With
recursive = truea rule may send files into a subdirectory of the watched directory; files that land there are not moved again. - Scan on start. By default rocas only handles files that appear while it runs. Set
scan_on_start = trueto organize the files already in the watched directories when it starts. - Cross-filesystem moves. A destination on another drive is copied and then the original removed.
With reload = true (the default), rocas reloads rocas.toml shortly after you save it. It listens for file-system events on the config directory, so an idle rocas does not poll the file; with poll = true that directory is polled like the watched ones. Editors that save by replacing the file are handled, and so is creating rocas.toml after rocas has started, even when its directory does not exist yet: rocas then watches the nearest existing parent directory (not recursively) until the directory appears, and moves the watch down to it. New rules, destinations and the settings above apply without a restart. If the new file is invalid, rocas logs the error and keeps running with the previous configuration.
The binaries on the Releases page include self-update: with check_for_updates = true rocas looks for a newer release on startup, and with auto_update = true it installs it. Builds from package managers, including the Nix package, are compiled without the self-update cargo feature; there check_for_updates and auto_update are ignored and your package manager does the updating. To build without it yourself: cargo build --release --no-default-features.
Every option can also be set with a command-line flag or an environment variable. Precedence, lowest to highest: config file, environment, command line.
- Flags are the key path in kebab-case:
--watcher.recursive,--watcher.max-depth 2,--misc.log-level debug. On/off options take no value:--watcher.recursiveturns one on,--no-misc.check-for-updates(or--misc.check-for-updates=false) turns one off. - Environment variables are
ROCAS_plus the key path uppercased with_:ROCAS_WATCHER_RECURSIVE=true,ROCAS_MISC_LOG_LEVEL=debug. Lists are comma-separated:ROCAS_WATCHER_WATCH_PATHS=/a,/b. rocas --helplists every option with its default and environment variable name.rocas --version(or-V) prints the version.
rocas --boot # or: rocas -bToggles launching rocas when you log in (run it again to turn it off), then keeps running as usual. --boot is an action, not a setting: it is never read from the config file or the environment.
rocas --setupAsks a few questions in the terminal and writes rocas.toml for you: which folders to watch (and whether to look inside subfolders), which preset rules to turn on (Documents, Images, Videos, Audio, Archives, Installers, each with a destination you can change), what to do when a name already exists at the destination, and whether to start rocas when you log in. In builds with self-update it also asks whether to look for updates. The last screen shows the exact file before anything is written.
- Keys.
Up/Down(ork/j) move,Spacetoggles,Enterconfirms or edits,Tab/Rightgo to the next screen,Shift-Tab/Left/Backspaceto the previous one. In a text fieldEsccancels.q(outside a text field) orCtrl-Cquits without writing anything. - Presets. Matching is case-sensitive, so each preset lists every extension in lower and upper case (
*.jpg,*.JPG). Edit the file to add other spellings or extensions. - Existing file. If
rocas.tomlalready exists, the review screen says so and asksybefore replacing it. The file is written to a temporary name and renamed, so a running rocas never reads half of it. - Start on login. Turned on only if it is off; the wizard never turns it off. Use
rocas --bootto toggle it. - First run. Running plain
rocasin a terminal with no config file asksRun setup now? [Y/n], then goes on to start rocas. Nothing is asked when rocas runs from a service, from autostart, in a pipe, or with any other option. - Windows. rocas has no console of its own, so
--setupattaches to the one it was started from, or opens a new window when there is none. Start it withstart /wait rocas --setupin cmd (orStart-Process -Wait rocas --setupin PowerShell) so the shell does not compete for your keystrokes.
rocas bootis nowrocas --boot(or-b).- Existing files are never overwritten by default. 1.x replaced a file of the same name in the destination. Now the incoming file is renamed (
name (1).ext). Seton_conflict = "overwrite"in[misc]for the old behaviour, or"skip"to leave the incoming file alone. interval_millisonly applies withpoll = true. It used to have no effect on native watching. rocas now uses OS notifications and does not wake up while idle unless you enablepoll.- Partial downloads are ignored. Files matching the default
ignorelist are not moved. If you relied on moving one of those names, setignoreto your own list. - The config reloads on change. Set
reload = falseto disable that. - rocas never moves its own config file. A rule such as
*.tomlover a watch directory that containsrocas.toml(for example~/.config, watched recursively) skips that one file, however the path is spelled, while other files still match. Editing it triggers one reload. watch_pathis optional and defaults to your Downloads directory;log_filedefaults torocas.lognext to the config file.- Nix:
programs.rocas.watcher.watchPathdefaults tonull(your Downloads directory). - NixOS service: the module writes the config to
/etc/rocas/rocas.tomland runs rocas withXDG_CONFIG_HOME=/etc, so rocas reads it from there instead of a per-user config directory. The service hasStateDirectory=rocas, andservices.rocas.misc.logFiledefaults to/var/lib/rocas/rocas.lograther than a file next to the config. Setting it tonullgives rocas's own default (next to the config), which the service's read-only/etcdoes not allow.
Contributions are welcome! For major changes, please open an issue first to discuss what you have in mind. Bug fixes and improvements can go straight to a pull request.
The dev shell is devenv: run devenv shell (or let direnv load it), then check runs the same gate as CI: formatting, clippy, tests, docs, cargo deny, shellcheck and a spell check. The nix package and the NixOS and home-manager modules still come from flake.nix.
- @Aliwizzz - Logo/icon and idea
- @prdgn52627 — Name and banner
MIT — see LICENSE for details.