Property List Configuration#
Patcher uses a property list (.plist) file to store persistent settings, such as user interface customizations, setup status, and integration preferences. This file is stored in the Patcher folder of the Application Support directory in the user library:
~/Library/Application Support/Patcher/com.liquidzoo.patcher.plist
Property List Format#
Changed in version 2.1.1
The property list format has been updated to be more simplified, aiming to help end-users interact or modify the settings in a more efficient manner. Below is a summary of the changes.
Setting |
Old Key |
New Key |
|---|---|---|
UI settings |
|
|
Header text |
|
|
Footer text |
|
|
Font name |
|
|
Regular font location |
|
|
Bold font location |
|
|
Company logo |
|
|
Setup completion |
|
|
Installomator support (ref) |
N/A |
|
The new format introduces consistent naming conventions and moves the setup completion flag (setup_completed) to a top-level key-value pair rather than being nested under the Setup dictionary. Additionally, the user interface settings dictionary has been renamed from UI to UserInterfaceSettings to improve clarity and maintain consistency.
Automatic Conversion#
For existing users, Patcher will automatically migrate to the new format if the previous format is detected. A backup file is also created in the event the migration fails so settings can be revived if necessary.
def migrate_plist(self) -> None:
"""
Modifies existing property list files in v1 format to v2 format.
A backup file is created in the event migration fails so user settings are perserved.
"""
data = self._load_plist_file()
if not self.needs_migration():
return
self.log.info("Old property list format detected. Migrating...")
backup_path = self.plist_path.with_suffix(".bak")
shutil.copy(self.plist_path, backup_path) # Save backup
self.log.info(f"Backup property list file created: {backup_path}")
ui_dict = data.get("UI")
new_data = {
"setup_completed": data.get("Setup", {}).get("first_run_done", False),
"enable_installomator": data.get("Installomator", {}).get("enabled", True),
"enable_caching": True,
"UserInterfaceSettings": {
UIConfigKeys.HEADER.value: ui_dict.get("HEADER_TEXT"),
UIConfigKeys.FOOTER.value: ui_dict.get("FOOTER_TEXT"),
UIConfigKeys.FONT_NAME.value: ui_dict.get("FONT_NAME"),
UIConfigKeys.REG_FONT_PATH.value: ui_dict.get("FONT_REGULAR_PATH"),
UIConfigKeys.BOLD_FONT_PATH.value: ui_dict.get("FONT_BOLD_PATH"),
UIConfigKeys.LOGO_PATH.value: ui_dict.get("LOGO_PATH"),
},
}
try:
self._write_plist_file(new_data)
self.log.info("Property list migration completed.")
except PatcherError:
raise
For a full example of the new format, see the XML configuration at the bottom of this page.
Modifying the Property List#
The property list can be modified using PlistBuddy or a code editor of your choice (VSCode, BBEdit, CodeRunner, etc.). The defaults command can also be leveraged, but is not recommended as it has trouble updating keys nested within dictionaries.
Editing Binary Property Lists
By default, property list files are stored in binary format, which text editors cannot modify directly. If you are planning to make changes in an IDE like VSCode or BBEdit, convert the file to XML format first:
$ plutil -convert xml1 ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
Once finished making modifications, convert it back to binary format:
$ plutil -convert binary1 ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
Font Customization#
To change the font, update the font_name, reg_font_path and bold_font_path values in the UserInterfaceSettings dictionary.
$ /usr/libexec/PlistBuddy -c "Set :UserInterfaceSettings:font_name 'Helvetica'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
$ /usr/libexec/PlistBuddy -c "Set :UserInterfaceSettings:reg_font_path '/path/to/Helvetica-Regular.ttf'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
$ /usr/libexec/PlistBuddy -c "Set :UserInterfaceSettings:bold_font_path '/path/to/Helvetica-Bold.ttf'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
Adding a Company Logo#
Patcher allows branding with a company logo. The logo must be in PNG, JPEG, or a Pillow-supported format.
To configure a logo:
$ /usr/libexec/PlistBuddy -c "Set :UserInterfaceSettings:logo_path '/path/to/logo.png'"
For more details on customizing fonts and adding a company logo, see Customizing Reports
Installomator Support#
To disable Installomator support:
$ defaults write ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist enable_installomator -bool false
Full Example Configuration#
Here is an example configuration with all available keys and values:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>UserInterfaceSettings</key>
<dict>
<key>header_text</key>
<string>AnyOrg Patch Report</string>
<key>footer_text</key>
<string>Made with <3 from IT</string>
<key>font_name</key>
<string>Assistant</string>
<key>reg_font_path</key>
<string>/Users/spesh/Library/Application Support/Patcher/fonts/Assistant-Regular.ttf</string>
<key>bold_font_path</key>
<string>/Users/spesh/Library/Application Support/Patcher/fonts/Assistant-Bold.ttf</string>
<key>logo_path</key>
<string>/Users/spesh/Library/Application Support/Patcher/logo.png</string>
</dict>
<key>setup_completed</key>
<true/>
<key>enable_installomator</key>
<true/>
</dict>
</plist>