Tutorial: Preferences Files: The Complete Story (Part IV)

Ted Landau

In this installment of our continuing series on preferences (.plist) files, we finally delve into the details of how to interpret and edit .plist files. I'll be primarily showing you how to do make changes using Apple's Property List Editor (PLE) but I will also briefly cover how it can be done using the defaults command in Terminal.

[Note: As you read along, if it seems as if something is missing, it's probably because it was covered in a previous part of this tutorial series; you can catch-up on all the fun by reading Parts I & II and Part III.]

PART IV: How to interpret and edit .plist files

Q. Okay. I've opened a .plist file in Property List Editor. How do I begin to make sense of what I am seeing?

A. Let's use a relatively plain and simple .plist file to show just how easy this can be: open com.apple.dock.plist (located in the Library/Preferences folder of your home directory). After it opens, you will likely see only one item listed: Root. This is the item that appears at the top level of virtually all .plist files. To see the actual properties (also called keys) of interest, click the disclosure triangle to the left of the word Root. You should now see a list similar what is displayed in Figure 1.

Figure 1. The com.apple.dock.plist file, as viewed in Property List Editor

Figure 2. The Dock System Preferences pane.

For each item in the list, there are entries in three columns. The columns are:

• Property List. This column contains the name of each listed property. Happily for us, the name is often a common-sense English indication of what the property does. For example, "autohide" refers to whether the "Automatically hide and show the Dock" option is enabled or not. Pretty obvious, once you look at the relevant user-accessible settings in the Dock System Preferences pane (as seen in Figure 2). Similarly, "magnification" refers to whether or not the Magnification option is enabled, as again located in the Dock pane. The "trash-full" property is a bit different; it indicates whether the Trash icon in the Dock itself shows the empty or full Trash icon.
  
  
• Class. This column describes the class (or category) of the property. Your choices are limited to the selections in the pop-up menu, as shown in Figure 3:
  
  
  Figure 3. The Class pop-up menu.
  
  Before I explain what most of these classes mean, let me briefly describe the third column:
  
  
• Value. The data in this column contain, as its name indicates, the current value or status of the property. This is what typically gets modified automatically when, for example, you change the status of an item in a Preferences dialog. It is also what you will most often be modifying when editing a .plist file yourself.

Suppose, for example, you were designing software and you wanted to have a preference that indicates whether or not a given checkbox is enabled, such as the Magnification checkbox mentioned above. You would likely want the Class to be Boolean, as this is limited to a binary pair of values, either Yes/No or True/False. In Property List Editor, when you select the Boolean class, the Value column is restricted to a pop-up menu that just has Yes and No options.

The String and Number classes refer to values that are either text strings or numbers, respectively. For example, the "largesize" property indicates how large the dock should enlarge (in pixels) when it is magnified (assuming Magnification has been enabled). The normal maximum is 128.000000. The Class of this property is Number. This means that the 128.000000 value should be treated as a number, not simply a text string. Similarly, the "mineffect" property describes whether the Genie or the Scale effect has been selected in the "Magnification using" option. It's value must be either the word "genie" or "scale," the words that appear in the pop-up menu in the Dock System Preferences pane. As these words are text, with no numeric value, String is the selected class.

Note: If you enter an invalid value, such as a misspelled word for a String class item, the property setting will likely be ignored and the property will revert to its default value. In most cases, text in the Value column is not case-sensitive; however, property names are typically case-sensitive. Capitalize a name that should be in lower-case (or vice versa) and it will not work.

The Array and Dictionary classes function similarly. In each case, they describe a property that does not have a value listing of its own. Instead, it is the parent of other properties. For Dictionary items, the property name is a text string; the order of the property listings is of no consequence. For Arrays, the names of the properties are usually numbers and are treated as having numerical value; this is because the listing order is of significance. You can see an example of each of these classes in Figure 4.

Figure 4. Another look at the com.apple.dock.plist file. Note the numerically-named items in the persistent-apps Array property. The file-data property is an example of a Dictionary item (as is the Root property itself).

The persistent-apps array is a list of the applications that are permanently included in the Dock. It is an array and the numerical values of each property name thus matter: they indicate the order in which the items appear in the Dock. The Finder is always the first item in the Dock and does not even appear in this list. On my Mac, item 0 is Dashboard and item 1 is the System Preferences application (I moved it there from its default location). You can see all this (without looking at the Dock itself!) by expanding the numeric items to reveal their children until you find the ones that list the application name. In Figure 4, for example, the highlighted "_CFURLString" item shows the application name for item 1 as "/Applications/System Preferences.app/". The "file-label" item a few lines below similarly lists "System Preferences" as its value.

Q. Some of the property names make no sense to me. And their values are equally incomprehensible. What gives?

A. Yes, this is not all that unusual. Remember, the main function of these .plist file properties is to tell the application what settings to use. As long as the application understands what to do with the information, it does not matter whether or not you do. In most cases, these "opaque" items refer to things you would never want to modify anyway. Unless you specifically read about their function elsewhere, just ignore properties that you do not understand. You will have enough to do with those items that do appeal to common sense.

Q. OK. Let's at last suppose I want to edit a .plist file, perhaps to change a value listing. How do I do it?

A. We are now at last at the heart of this tutorial. Note: Always make sure you have a backup copy of a .plist file before editing it; that way, if you mess things up and need to get back to the original file, you can easily do so. That said, to use Property List Editor to make editing changes to an existing .plist file, start with these three basic steps:

1. Quit the application that uses the .plist file.
   
   
2. Open the .plist file in Property List Editor and select the "Root" item.
   
   
3. Click the disclosure triangle to reveal the list of properties.

Next:

• If the item is Boolean, changing its value could not be simpler. Just select the currently unselected item from the Yes/No pop-up menu in the Value column.
  
  
• For most other Classes (such as String and Number), double-click the Value text; it becomes highlighted as an editable text-box (as shown in Figure 5). Change the value as you like. You can similarly change the name of a property (although it would be very rare that you would want to do this).
  
  
• Changing a property's class is done via the Class pop-up menu.
  
  
• For dictionaries and arrays, you cannot change the value. All you can do is edit the properties that are "children" of the array or dictionary property.

When done, save the file. In some cases, you may need to take some action, such as logging out and logging back in, before the change takes effect.

Figure 5. Editing the value of the "mineffect" property.

Q. Suppose I want to add a new property or entirely delete an existing one. How do I do that?

A. Last time, we covered the primary reason why you might want to add a new property: to add a hidden property (that is, one not included in the .plist file by default). Here's how to do it:

1. After doing the three basic steps cited above, and with the Root item still selected, the button directly above the Root item should read New Child. Click it. This will add a new property, titled "New Item."
   
   
2. You can now edit the item, filling in the desired name, class, and value.

Note: If you select any expanded dictionary or array item, you can similarly click the New Child button. This will create a new item that is a child of the selected item, rather than of Root. Alternatively, if you select an unexpanded dictionary or array item (i.e., its children not visible), or if you select any other Class of item (e.g., String, Boolean), the New Child button becomes a New Sibling button. Clicking this button creates a new item at the same level as the selected item.

To delete an existing property, simply select it and click the Delete button. Done.

Figure 6. Property List Editor's New Sibling and Delete buttons

Q. Suppose I want to copy an entire property (key name, class and value) from one .plist file and paste it in another. Can I do this?

This sort of copy/paste could be useful, for example, to transfer customized properties from a .plist file to another version of the same file. The problem is that, as mentioned in the first installment of these series, Property List Editor does not allow you to do this. However, third-party .plist file editing utilities, such as PrefSetter and PlistEdit Pro, do provide this option.

Q. What about using Terminal to work with .plist files?

A. Yes, you can use Terminal to do anything you can do in Property List Editor (and beyond!). The command that you use is defaults. Personally, I never use this command to view a .plist file. For that, Property List Editor works much better for me. However, defaults can sometimes be more convenient for editing a file, especially for adding new (e.g., hidden) properties. To use defaults for editing a .plist file, use the write option. More specifically, use the following format:

defaults write {name of .plist file} {key} {-class} {value}

As an example, here is how to use Terminal to add the property to the Finder's .plist file that puts a Quit item in the Finder's File menu (I covered how to do this using PLE in the previous part of this series):

defaults write com.apple.Finder QuitMenuItem -bool Yes

This will add an item called QuitMenuItem to the com.apple.Finder.plist file, assign it to the Boolean class with a value of Yes. If you omit the class argument, the item is assigned to the String class by default. You can always confirm that the change was made as expected, by opening the file in Property List Editor after making the change.

If you enter the above command for an item that already exists, it will modify the item to match what you entered. For example, to later change the value of the QuitMenuItem to No, you would type:

defaults write com.apple.Finder QuitMenuItem No

Because, in our example, the item already has a Boolean class assigned, you do not need to re-enter that argument.

Here are a few other technical notes regarding defaults:

• The entry for the .plist file name should not include the .plist extension itself.
  
  
• If you enter a .plist file name that does not exist, a new file with that name will be created.
  
  
• The defaults command assumes by default that the .plist file you want to modify is located in the Library/Preferences folder of the currently logged-in user. To access a .plist file in any other location, use the full path for the file as its file name (e.g., /Library/Preferences/com.apple.AppleFileServer for the com.apple.AppleFileServer.plist file in the root level Library/Preferences folder).
  
  
• Modifying items that are children of dictionary or array items can be tricky to do in Terminal. I recommend using Property List Editor instead.
  
  
• To learn more about the defaults command, launch Terminal and type: man defaults.
  
  
• The examples given in the man defaults output show double quotes (") around the key name and single quotes (') around the value. However, unless there are blank spaces in the entry, I have found that the quotes are not needed.

Q. Sometimes, when I try to save a modified file in Property List Editor, I get an error that says "I do not have appropriate access privileges." What gives?

This is unlikely to happen for files in your Home directory, but may occur for .plist files located elsewhere (such as in the System folder or in Unix directories). It happens if you do not have "write" access for the file. In most cases, you are best off not modifying these files anyway, so it's just as well that Property List Editor turned down your request. In one case, for example, after I made a change to a .plist file in the /System/Library/CoreServices folder, my Mac would crash on restart. I needed to use single user mode to access the file and fix the problem. So be cautious!

However, assuming you are certain you want to make changes to a permission-restricted file, there are several solutions. One, as suggested in the error message itself (as seen in Figure 7) is to change the access privileges of the file via Get Info. You can do this only if you are an administrator, but I recommend against it in any case. It's best to leave privileges unchanged, as a change could potentially prevent the file from being accessed by the OS when needed.

Figure 7. The message that appears in Property List Editor if you do not have permission to modify a .plist file.

A better alternative is to use a utility such as Pseudo to launch Property List Editor as the root user. You will now be able to save the file, because the root user has the necessary permission.

However, I often find the simplest approach is to use Terminal. All you need to do is enter commands as just described here, except precede them with the sudo command (and provide your administrator password when asked). Because it is likely that the these "unsavable" .plist files are not located in your Home directory's Preferences folder, you will also need to specify the absolute path to the .plist file. Here's an example, using a setting in the com.apple.loginwindow.plist file:

sudo defaults write /Library/Preferences/com.apple.loginwindow RetriesUntilHint 1

Assuming that you previously enabled "Show password hints" in the Login Options of the Accounts System Preferences pane, this change will reduce the number of incorrect login attempts needed to trigger the appearance of the password hint from 3 tries to 1.

In another example, you can disable the Guest option in Connect to Server dialogs (as briefly noted in the previous installment of this series) by editing the com.apple.AppleFileServer.plist file:

sudo defaults write /Library/Preferences/com.apple.AppleFileServer guestAccess No

Restart your Mac for the change to take effect.

Q. How about a couple of more examples of using all of this info to do some cool tricks with Preferences files?

A. Sure thing. Both of these next examples were also briefly mentioned (without details on how to make the changes) in the previous installment of this series. Here's the "how to do it" info:

• Magnification size. This change will increase the magnification size of Dock icons beyond the Max available in the Dock System Preferences pane. It's more for fun than any practical value.
  
  1. Open the Dock System Preferences pane. Click the checkbox to enable Magnification, if it is not already enabled. Move the slider to any location other than its current one. Close System Preferences. [These adjustments "set up" the .plist file for the key change you need to make.]
  2. Open com.apple.dock.plist (located in ~/Library/Preferences) in Property List Editor.
  3. Locate the property named "largesize". Change its value from whatever it is to 512.000000. Save the change.
  4. Open Activity Monitor, select the Dock process in the Activity Monitor window, click the Quit Process button and select to Quit the Dock. The Dock will quit and immediately relaunch. This gets your change to take effect.
  
  To see the enlarged icons, simply move your cursor to the Dock. To undo the change, there is no need to go back to Property List Editor; instead, just open the Dock System Preferences pane and move the Magnification slider to a different location.
  
  
• Dashboard Developer Mode. Adding this hidden property enables Dashboard options primarily designed to assist Widget developers in debugging their widgets. However, one option is of potential interest to all users: the ability to move a widget to the Desktop (allowing it to remain visible even when Dashboard is not active.
  
  1. Open com.apple.dashboard.plist (located in ~/Library/Preferences) in Property List Editor.
  2. Click the disclosure triangle next to the Root item to display the property list. Next, click the New Child button.
  3. Change the name of the newly created item to "devmode". Change its class to "Boolean" and give it a value of Yes. Save the change.
  4. To get the change to take effect, you again need to relaunch the Dock (as described in the previous example).
  
  You are now ready to make a "permanent" widget. To do so:
  
  1. Click the Dashboard icon on the Dock. Click-hold the mouse button for the desired widget.
  2. Drag the widget to the Desktop. While still holding it, press the shortcut to hide Dashboard (typically F12, as found in the Dashboard and Exposé System Preferences pane).
  3. Release the mouse button.
  
  Everything should now have returned to normal, except that the Widget you dragged to the Desktop remains visible, even though you are not in Dashboard mode. Should you later want to get rid of it: hold down the Option key and move your cursor over the Widget until the X icon appears in the upper left corner; click it.

That's it for this episode of Preference Files Complete. We've come a long way, but there is still a good distance to go before we are done with the saga. Yet to come: more on working with .plist files outside of the ~/Library/Preferences folder; the GlobalDomain and the invisible .GlobalPreferences .plist files; detecting corrupt .plist files using either the plutil command or GUI utilities such as Preferential Treatment; troubleshooting application problems by deleting .plist files; working with .plist files in single user mode, and a list of my favorite .plist file hidden settings.

Ted Landau is the author of Mac OS X Help Line: Tiger Edition, where you can learn even more about .plist files.

Like what you've found in this tutorial? Get more troubleshooting guidance (updated daily) by subscribing to MacFixIt Pro.

Resources

More from Tutorials