What Are the Main Components of an organize Rule?

Updated

An organize rule is a YAML list entry built from four core parts: name, locations, filters, and actions. The locations block tells organize where to look, filters narrow that set down to the files you care about, and actions define what happens to each match. A rule only needs to be written once, then it runs the same way every time. This structure applies to organize v3, which the project describes as faster and with more actions, filters, and options than earlier versions.

The four components

name

A label for the rule. It appears in output and logs, so use something that identifies the job, such as "Find PDFs" or "Sort invoices". It does not affect which files are matched.

locations

The folders organize should scan. Each entry is a path, and ~ expands to your home directory:

locations:
  - ~/Downloads
  - ~/Desktop

Adding subfolders: true makes organize descend into nested folders instead of only reading the top level. Without it, files in subdirectories are ignored.

filters

Filters decide which files from the locations are kept. They combine, so a file must pass all of them. The documentation lists filters for extension, file content, and EXIF tags, among others. Examples:

  • extension: pdf — only PDF files.
  • Content-based filters — read text extracted from PDF, DOCX, and similar formats, useful for renaming invoices by what is inside them.
  • EXIF filters — read camera metadata, useful for sorting photos into folder structures.

actions

Actions run on every file that survives the filters. The docs mention moving, renaming, and copying with conflict-resolution options, plus inline Python and shell commands for cases the built-in actions do not cover. A minimal action just prints a message:

actions:
  - echo: "Found PDF!"

A complete rule

rules:
  - name: "Find PDFs"
    locations:
      - ~/Downloads
    subfolders: true
    filters:
      - extension: pdf
    actions:
      - echo: "Found PDF!"

Read top to bottom: scan ~/Downloads including subfolders, keep files ending in .pdf, then print Found PDF! for each one.

How the parts interact

Component Question it answers Effect if omitted
name What is this rule called? Rule is unlabeled in output
locations Where do I look? Nothing to scan
filters Which files do I want? All files in the locations are treated as matches
actions What do I do with them? Nothing happens to matched files

The order matters conceptually: locations produce a candidate set, filters shrink it, actions consume the result. A filter that matches nothing means the actions never run.

Editing and testing

Run organize new to create a configuration, then organize edit to open it. If editing is awkward, organize show --reveal shows the configuration file location. Because organize can simulate everything before touching your files, you can confirm a rule matches what you expect before letting its actions move or rename anything.

Common sticking points

  • Forgetting subfolders: true — files nested below the listed folder are silently skipped.
  • Stacking filters too tightly — each added filter removes more files; if a rule stops matching, remove filters one at a time to find the culprit.
  • Expecting actions to run on non-matches — actions only see files that passed every filter.
  • Assuming a rule is safe because it looks right — use the simulation step first, especially for move, rename, and copy actions with conflict resolution.