Black Hole Help

← Back to topics

Clearing Recent Items

What It Does

This cleaner can be used to clear recent items lists in most applications' File > Open Recent menu.

Recent items are cleared based on the rules in the Clear Recent Items configuration panel accessible using the "..." button beside the corresponding cleaner in the main Black Hole window.

For Recent Items to Be Cleared Instantly

The corresponding application should be quit before the Clear Recent Items cleaner runs, using the Quit Applications cleaner or by manually quitting the application before cleanup. When the application is opened after cleanup, the Recent Items menu will be empty. If you do not do this, the recent items will disappear from the Recent Items menu after the application is quit, although some applications may keep the items in there even after being quit. Just to be sure, you should always add the application to the Quit Applications cleaner if there is a rule for that application in the Clear Recent Items cleaner.

Default Rules

Black Hole comes with a default set of rules that you can enable or disable based on your personal needs. By default no rules are enabled. If you add or remove items from the rules list, you can always go back to the default settings by clicking the "Default" button. This will reload the default set of rules.

Adding Your Own Rules

Black Hole guides your through the steps needed to add a new rule and does as much as it can to gather the required information. Still there could be times when Black Hole will not be able to create the rule automatically. In that case you will have to find the required information manually.

Here is what Black Hole does when you click on the "+" button in the Recent Items panel:

  1. You are presented with a dialog to choose the application for which you want to clear recent items.
  2. One you choose the application, Black Hole detects if there is a dedicated file used only for recent items. If that is the case, a rule is automatically created and you are done.
  3. If no dedicated recent items file was found, Black Hole searches through the application's preferences file for keys that could contain the recent items list. It then presents you with a dialog where you can see those keys and their content, then determine which one(s) contain the list of recent items. (Hint: Look for the filenames you can see in the application's recent items menu, or the word "alias" with lots of gibberish!) After you selected one or more keys, simply press the "Create" button and Black Hole will add a new rule with all the information filled in.
  4. If Black Hole could not find any relevant information, a dialog tells you so and you must add your new rule manually.
Please note that you should ideally backup the preferences file before testing your new rule to make sure you can go back to the previous settings should you choose the wrong key. You can show the applications's preferences file in the Finder using the "Show Preferences" button in the Found Keys window that pops up when keys have been found for the application you selected.

Also note that while the automatic rule creation often works, it does not always do so. If it doesn't work right away you may have to modify the rule manually.

Manually Adding Your Own Rules

Manually adding your own rules to clean recent items using Black Hole requires a certain level of expertise but it is not too hard as long as you know how to do it and you have the right tools. Let this section be a short tutorial on how application preferences work on Mac OS X and how to add rules for each application you use based on those.

To obtain the information you need to add rules you need to be able to open .plist files. The .plist extension is short for "Property List". To open property list files you need to download and install either Xcode (which contains an application called "Property List Editor") from Apple's developer website, or a standalone application such as PlistEdit.

There are typically two ways Mac OS X applications use to store their recent items lists and both of them involve a .plist file:

  1. Possibility: There is a plist file containing only recent items

    Often, there is a single .plist file in the ~/Library/Preferences folder with a name similar to this:
    com.companyname.ApplicationName.LSSharedFileList.plist

    Simply deleting this file results in the clearing of recent items for the corresponding application. To do so, check the "Delete File" box in your rule. Keys will be ignored when the option to delete the file is checked, as evidenced by the greyed-out "Keys" field.

    If you find any other file containing the recent items, be it a .plist or not, you can make Black Hole delete the file using the same checkbox. To open and inspect property list files you need to download and install either Xcode (which contains an application called "Property List Editor") from Apple's developer website, or a standalone application such as PlistEdit.

  2. Possibility: There is a recent items key in the application's preference file

    1. Find and open the application's preference file

    Almost all applications have a preference file in the ~/Library/Preferences folder (where "~" is your home folder). Going in the Finder, pressing ⌘+⇧+G and typing "~/Library/Preferences" in the text field will get you there.

    The file name of a preference file looks like this:
    com.companyname.ApplicationName.plist

    For example, Black Hole's and Safari's preference files are:
    net.irradiated.Black-Hole.plist
    com.apple.Safari.plist

    Find the preferences file for the application you want to clear recent items for and open it using the property list editor you installed earlier (see above).

    2. Locate the key containing the recent items list

    The property list file contains keys and their associated values. A key is simply the name of a setting, while the value contains the setting's value itself. In the case of QuickTime Player 7, if we open its .plist file (~/Library/Preferences/com.apple.quicktimeplayer.plist) using a property list editor, we see this:

    As you can see, you will find a key named "QTPRecentDocumentsUserDefault" in the property list which in my case contains three items. By expanding those three items using the disclosure triangles I can see the names of the files listed in my QuickTime Player 7's Recent Items menu, in that case "Movie.mov" and two other entries. That means I found the right key to delete using Black Hole.

    The name of the key that's used to store the recent items list is different from application to application most of the time. If you open Black Hole's Recent Items cleaner configuration panel you will see the keys that are deleted for each listed application. You can use those as a starting point to know what kind of key names to look for.

    When adding an application, look for a key containing the word "recent" of type "Dictionary" or "Array". You will find the appropriate key most of the time.

    3. Create a rule in Black Hole

    Once you collected the required information (the .plist file's location and the key's name), you can create your new rule in Black Hole. Here's what you must fill in:

    1. Is the rule active? (Will recent items be cleared for this application or not when cleaning?)
    2. A description for the rule, generally the name of the application, but you can put anything in there.
    3. The path to the .plist file you found earlier.
    4. Whether to delete the whole .plist file (checked) or delete specified keys within it (unchecked).
    5. The keys to delete if the "Delete File" checkbox is unchecked. This is the key you found earlier. You can also clear multiple keys by separating them with commas.

    If all goes well the recent items will be cleaned for each added application when Black Hole runs (if the rule is active, which it is by default). Congratulations!

    Note: If you mistakenly check the option to delete the file when in fact you wanted to delete a key within it, your preferences will be reset for this application (the .plist list file will be deleted). The .plist file will be re-created when the application is launched again.

    4. Send me the info!

    If you want to do so, you can send me the details for your custom rule. If the rule is valid I will add it to Black Hole's default rules list for others to use. If you find a problem with a default rule, please inform me ASAP so I can fix it. You can send me your rule using the "Submit Rule..." button in the Recent Items panel.