Understand the Logic of Rules

In the simplest case, where a folder has only one rule and that rule has only one condition and one action, Hazel’s logic is pretty self-explanatory: either the rule matches a file or folder and runs its action, or it doesn’t. However, as you create more (and more-complex) rules, you may encounter ambiguous situations in which Hazel behaves in an unexpected way. It can help to understand the logic by which Hazel applies rules.

The basic process is this:

Hazel tests the conditions of its first rule against the first file or folder in the monitored folder.

If the conditions match, Hazel runs the action(s) of that rule, in order, and then moves on to the next file or folder .
If the conditions do not match, Hazel tests the conditions of its next rule against the first file or folder, and so on until it has tried all the rules.

Hazel continues like this until it finds a match or runs out of items to check in the monitored folder.

You can alter this default behavior in certain ways if you need to achieve a particular effect.

Here are further details about Hazel’s logic, and examples of each one, to help guide your efforts:

Hazel rules operate equally on both files and folders.

In general, files and folders are treated the same way in both conditions and actions. There are, however, a few exceptions—for example, it’s possible to specify a rule condition in such a way that it applies only to files or only to folders, and the “Run rules on folder contents” action applies only to folders.
Only the first matching rule runs on any given file or folder.

Suppose you have two rules for a folder. The first looks for file names starting with “A” and tags them Red. The second looks for files with a .png extension and opens them in Preview. Now you put a file named “Apple.png” in the monitored folder. The first rule matches (because it starts with “A”) and applies the Red tag. But the second rule does not run, because a rule has already matched the file. On the other hand, if you put a file named “Banana.png” in the monitored folder, only the second rule will run—it will open the file in Preview.

If you need both rules to apply, you can add the “Continue matching rules” action to the first rule. That action tells Hazel to override its normal behavior and process the file through the next rule, even though a match has already occurred. If the next rule matches, however, Hazel won’t try any subsequent rules unless those rules also include the “Continue matching rules” action.

Because Hazel’s rules operate this way, you should pay careful attention to the order of your rules. If you need multiple actions to apply to complex combinations of attributes, consider using nested conditions .

As long as a file is not moved from the monitored folder, Hazel will continue to run that file through its rule list in subsequent passes.

Let’s say you have a rule that looks for files with a creation date more than 3 days ago and, if one is found, it’s moved to your Desktop. A newly created file appears in the folder, and the rule does nothing, because its creation date is too recent. But as long as the file is still in that folder 3 days from now, the rule will move it to your Desktop at that point.

Hazel checks and acts on only the files and folders at the top level of the monitored folder by default.

Imagine a Hazel rule is attached to your Downloads folder, and that rule displays a notification for every newly added file or folder. But inside your Downloads folder is a Research subfolder, and you drag a PDF into that subfolder. No notification will appear, because the file wasn’t added to the top level of the folder Hazel is monitoring. As far as the rule is concerned, the contents of that subfolder are invisible.

If you need Hazel to match against files and folders in subfolders of the main folder, there’s a way to do so, but be aware that this is an advanced feature. See Processing Subfolders for instructions.

If an action fails, subsequent actions do not run for that file.

If a rule has five actions and the third one fails (for example, it encounters a permissions error when copying a file, or a destination folder is missing), actions four and five will not run on that file. However, Hazel will continue trying to run the actions on subsequent passes until it succeeds (as long as the file still matches the rule).

If a rule matches a file or folder, that rule will not reapply its actions on a subsequent pass.

Hazel keeps track of which files or folders have matched which rules, and once a match has occurred and the rule’s action(s) have run successfully, the rule ignores that item the next time through. This approach prevents Hazel from running in endless loops.

For example, suppose you have a rule that looks for apps in the monitored folder and opens them if found. An app appears in the folder, and the rule opens it. Then you quit the app. Hazel won’t keep opening the app every time it examines that folder, even though the app still matches your rule. Likewise, if a rule modifies a file (for example, adding a tag) and you undo or change that modification manually, the rule won’t reapply it. However, if you change the rule’s conditions, Hazel will check them against the file and run the actions if they match; similarly, if an item stops matching a rule, and then later matches it again, Hazel does run the rule again. In addition, if the file or folder matches another rule, later in your list, that rule’s actions will run.

You can exclude files from subsequent rules by using the “Ignore” action.

You can use the fact that Hazel only runs the first matching rule on any file to effectively exempt certain files from being acted on by other rules in your list. For instance, let’s say you have a rule that monitors your Downloads folder and copies all PDFs to your Desktop. But you want to be sure that rule doesn’t apply to any PDFs that have “NSFW” in their filenames. You can add a rule— at the beginning of your rules list —with a condition “Name matches NSFW ” and set that rule’s action to “Ignore.” Whenever an item matches that condition, the action runs, but since the action is to do nothing, no further rules apply to that item.

You can create a catch-all rule for files and folders that don’t match any other rules.

If you want to have a default action run on files and folders that don’t match any of your other rules, give your last rule the single condition “Any file” and then add whatever actions you like. Since “Any file” matches, as it says, any file (as well as any folder), it will match anything that has gotten through all the rules preceding it.