apple-tags-migrator

A Python utility for backing up and restoring macOS Finder tags (labels) using extended attributes. This tool allows you to preserve file tags across migrations, backups, or system changes by storing tag data in a JSON database and restoring it later.

Features

• Backup Mode: Traverse a directory tree and save all Finder tags to a JSON file
• Restore Mode: Apply tags from a JSON backup to files on the filesystem
• Parallel Processing: Uses multiple threads for faster processing of large file sets
• Dry-Run Support: Test restore operations without making actual changes
• Error Handling: Robust handling of I/O errors with user-prompted retry logic
• Global Pause Control: Handles transient network issues (e.g., VPN disconnections) gracefully
• Logging: Optional detailed logging of all restoration actions
• Verbose Output: Real-time progress reporting during operations

Requirements

• macOS: This tool is macOS-specific due to its reliance on the xattr command and Finder's extended attributes
• Python 3.6+: The script uses modern Python features like type hints and f-strings
• Permissions: Read/write access to files and extended attributes (may require elevated permissions for system files)

Installation

No installation required. Simply download or clone the repository and run the Python script directly:

python AppleTagsScript.py --help

Usage

Backup Tags

To backup all Finder tags from a directory tree:

python AppleTagsScript.py --backup --root /path/to/directory --db tags_backup.json

This will traverse the specified directory, collect all file tags, and save them to tags_backup.json.

Restore Tags

To restore tags from a backup (dry-run by default):

python AppleTagsScript.py --restore --root /path/to/directory --db tags_backup.json

To perform an actual restore (live mode):

python AppleTagsScript.py --restore --root /path/to/directory --db tags_backup.json --live

Command-Line Options

• --root PATH: Root directory to traverse (required)
• --db PATH: Path to JSON database file (required)
• --workers N: Number of worker threads (default: 2x CPU cores)
• --backup: Run backup operation
• --restore: Run restore operation
• --live: Execute changes during restore (default: dry-run)
• --log-file PATH: Optional log file for restoration actions
• --verbose: Print detailed progress to terminal

Examples

Basic Backup

python AppleTagsScript.py --backup --root ~/Documents --db my_tags.json

Backup with Custom Thread Count

python AppleTagsScript.py --backup --root /Volumes/ExternalDrive --db external_tags.json --workers 4

Dry-Run Restore

python AppleTagsScript.py --restore --root ~/Documents --db my_tags.json --verbose

Live Restore with Logging

python AppleTagsScript.py --restore --root /Volumes/NewDrive --db my_tags.json --live --log-file restore_log.txt --verbose

Notes

• macOS Only: The script uses macOS-specific extended attributes and the xattr command
• Permissions: You may need administrator privileges to access tags on system files
• Large Directories: For very large directory trees, increase --workers for better performance
• Network Drives: The tool includes retry logic for network-related errors
• Tag Format: Tags are stored as raw binary plist data in hexadecimal format
• Color Tags: Supports both named tags and color-only tags

License

This project is licensed under the MIT License - see the LICENSE file for details.