Processing Subfolders

When Hazel checks your rules against the item in a monitored folder, it normally treats files and folders the same—for example, a Move action moves either a file or a folder if it matches your conditions, and a Rename action renames either a file or folder if it matches.

As a result, Hazel normally ignores specific changes inside subfolders of the monitored folder. So, suppose you’re monitoring your Downloads folder, and inside that is a folder called Research. If you have a rule that matches any PDF document and opens it in Preview—and you download a PDF to your Downloads folder, that file will open. But if you download a PDF directly to the Research subfolder, the rule won’t match, because Hazel ignores what goes on inside subfolders, unless you expressly tell it to examine them.

If you want Hazel rules to process the subfolders within a monitored folder, you can of course add those subfolders as monitored folders and create special rules just for them. But that’s not always practical—especially if you don’t know in advance what the subfolders’ names will be, or if there are quite a few of them and you want the same rules to apply to all of them.

To solve this problem, Hazel offers a special action: “Run rules on folder contents.” If a subfolder inside your monitored folder matches a rule containing this action, then the other rules in the list will also apply to that subfolder’s contents.

The easiest way to make a “Go into subfolders” rule is to configure it as follows. (For your convenience, you can download this rule here: subfolder.hazelrules . After you’ve downloaded the rule, open Hazel, select the folder you want to monitor, and drag the rule into its Rules list.)

This rule has just one condition (it matches any folder) and one action (“Run rules on folder contents”).

In many situations, this can be the whole rule. If it looks as though this rule doesn’t actually perform any actions, that’s because it doesn’t need to. Instead, it effectively modifies the behavior of your other rules, making their actions apply to items in subfolders. Therefore, it’s usually best to write all your rules as though they were operating on items at the top level of your monitored folder, and test them to make sure they function as intended. Then add the “Go into subfolders” rule to extend their behavior to items in subfolders of the monitored folder as well as the top level of the monitored folder.

To demonstrate why and how you might use the “Run rules on folder contents” action, let’s walk through a series of examples.

Imagine Hazel is monitoring a folder in which you often place music and image files. You initially have two rules: one that moves audio files to your Music folder and another that moves image files to your Pictures folder. Your rules might look like this:

These rules work fine for individual files, but what if you drop a folder full of images or audio files into your monitored folder? Nothing would happen, because by default, Hazel matches only top-level items in the monitored folder, and the folder containing images or audio files does not, itself, match your rules. So you can add a third rule—the “Go into subfolders” rule described above:

This new rule makes the other rules for this folder apply to subfolders as well. So now if you drag a folder of photos into your monitored folder, they’re all moved to Pictures, and if you drag a folder of MP3s into your monitored folder, they’re all moved to Music. Your existing rules did not have to change at all; they merely had their scope of operation expanded.

So far so good, but now you may find that your monitored folder contains empty subfolders! That’s because Hazel moved their contents (photos or audio files) to other locations. If you want to delete the empty subfolders, you can add a fourth rule—call it “Delete empty folders.” It would look like this:

But wait! This new rule matches folders (because of the condition “Kind is Folder”) and so does the “Go into subfolders” rule. By default, Hazel applies only the first matching rule in the list to any given item (see Understand the Logic of Rules ), so if “Go into subfolders” comes before “Delete empty folders,” then the “Delete empty folders” rule will never run, because all folders will already have been matched. So, since this new rule is more specific (it applies only to certain folders, not all folders), we put it before “Go into subfolders,” like so:

Let’s walk through how this will work. Suppose you drag a folder called “My Tunes” into your monitored folder. The presence of the “Go into subfolders” rule in the list means that each of the other rules will apply to folders within the monitored folder, so the “Move audio files to Music” rule runs and moves the files out of the “My Tunes” folder. Then the “Delete empty folders” rule matches the now-empty “My Tunes” folder and moves it to the Trash. But if the “Delete empty folders” rule had come after “Go into subfolders,” it would never have had a chance to run, because the “Go into subfolders” rule itself would already have matched that folder. (Another way to achieve the desired result would be to keep the “Go into subfolders” rule first, but add the “Continue matching rules” action to it, so that a match won’t block later rules from applying as well.)

To take this example even further, suppose we want only some folders in our monitored folder to be processed this way. For example, you want the first two rules to operate only on files inside folders whose names start with the word “Media.” To do this, you could modify the “Go into subfolders” rule by adding a second condition that specifies the folder name:

Once you’ve made that change, dragging a “Media Collection” folder into the monitored folder will trigger the rule, whereas dragging a “My photos and music” folder into the monitored folder will not.

Processing subfolders can get tricky, so here are a few tips you should keep in mind:

Keep your “Go into subfolders” rule separate from your other rules—there’s no need to combine everything into a single rule, and trying to do so is likely to produce undesirable results.
The “Run rules on folder contents” action will fail if it acts on anything other than a folder. Be sure you use a Kind is Folder condition (as shown above) to ensure that non-folder items do not match. And don’t add conditions or actions to your “Go into subfolders” rule that refer to files—leave those for other rules. (If the rule is matching a file and doing something with it, then it can’t match a folder as well.)
Running rules on folder contents is recursive—that is, Hazel will keep going into subfolders of subfolders of subfolders (and so on) unless you tell it not to. If you want a specific rule (that is, a rule that comes after “Go into subfolders” in your list) to stop at a certain subfolder depth, add a condition to that rule with the attribute “Subfolder depth”—for example, “Subfolder depth is greater than 2.” (In this context, a depth of 0 means the top level of the monitored folder. An item at the top of a subfolder within the monitored folder will have depth 1, and so on.) If you want to be sure all your rules stop at a certain subfolder depth, add the “Subfolder depth” condition to the “Go into subfolders” rule above.
Hazel runs rules on folder contents in order, from the top down. That is, if it matches Folder A at the top level of your monitored folder, it then works its way through everything in Folder A, and if one of those items is Folder B (which also matches), it then goes through everything in Folder B and so on. When it’s finished with Folder B’s contents, it pops back up to Folder A and finishes checking its remaining contents, and when it’s finished with those, it pops up another level to finish checking whatever’s left at the top level of the monitored folder.
If the monitored folder has a very deep hierarchy of subfolders, processing them repeatedly can take a long time and can negatively affect Hazel’s performance. For best results, use this approach on relatively shallow folder hierarchies, or use the “Subfolder depth” attribute to limit how deep the rules go.
As a reminder, a good rule of thumb is to first create rules that will process files as if they were at the top level of the monitored folder, and then add the rule above to tell Hazel to go into subfolders.