The Finder’s tag system is a commonplace tool which remains underused, and many who do use them use relatively little of their power. It’s also one of few instances in which Apple gives the user control over metadata stored as extended attributes (xattrs). This article looks at how Finder tags work.

Using tags

Finder tags are exposed to the user in the Finder’s Preferences window, where they’re given their own section, with simple but powerful tools for use and customisation.

Each tag consists of two elements: a colour which can be none or chosen from the standard range of seven: red, orange, yellow, green, blue, purple, and grey, and a text label. When you use the standard macOS tags, their text labels are simply the colour names. You can change those standard labels by Control-clicking on them, or remove them if you wish.

Adding a new tag is obvious, by clicking on the + tool at the foot of the tag list, and clicking on the – tool there removes the selected tag.

The xattr which stores a file or folder’s tag contains the two elements of each of its tags, and can hold multiple tags. When you add your own custom tags, items marked by them have a xattr which contains the label of your custom tag and its set colour, from the range of seven plus no colour.

The Finder manages tags for you. For example, if you customise one of the standard tags by changing its name, say from Red to Urgent, then the Finder automatically changes all items marked with that tag to show the label Urgent. That tag remains associated with that file or folder: when you copy that item across to another Mac, the tag remains attached to it, and on that second system should continue to show the same colour and label. The same applies to custom tags which you might add.

The important exception to this is if the item is moved using a method which doesn’t preserve its metadata (xattrs), which occurs on some file systems such as NFS, and using some command line tools. Some backup methods may also not preserve metadata, and will strip all your tags; Time Machine preserves them all.

Tags are widely supported in the Finder, macOS tools, and apps. When you show tags in the Finder’s sidebar, you can view items with only a specific tag by selecting that tag in the sidebar of a Finder window. The same feature works in file open and save dialogs in all apps using the standard macOS dialog too. You can further refine a tag-based listing by opting to sort those files in date or other orders, and you can group by tags too.

There are several different ways to assign one or more tags to any file or folder, and you can use the same method to remove tags from them. The simplest is probably using the Finder’s contextual menu. Note that if you remove a tag from the list in the Finder’s Preferences, that tag is also removed from every item which was tagged with it. You can use that to your advantage if you use a custom tag to work on a specific project: when that is complete, and the documents are archived, you can search for any outlying items which still have that tag, then delete the tag in Finder Preferences once you have cleared them away.

You can tag files automatically in shell scripts, AppleScript, and many other languages supported on macOS. If you want to do this, one easy approach is to install tag, available in Homebrew and MacPorts, or from its Github site.

Finder tags can also be used as a criterion in Spotlight searches, although these are based not on the tag colour but its text, such as Important for a red tag labelled Important. You’ll need to add the Tags item to the Finder’s list of search criteria before you can use it to find items in the Finder.

The xattr

Finder tags are stored in xattrs of type com.apple.metadata:_kMDItemUserTags. They consist of a binary property list containing a little UTF-8 text. This is an NSArray consisting of Strings, each containing a tag name, followed by the newline character, followed by the colour number (0-7). The array may be empty.

Colour numbers used are:

• none, 0
• grey, 1
• green, 2
• purple, 3
• blue, 4
• yellow, 5
• red, 6
• orange, 7.

Thus a tag name might read Red\n6, or Orange\n7 Green\n2 for two colours, where \n represents the newline character 0a.

When the Finder writes a tag xattr to an item, is also adds a null com.apple.FinderInfo xattr of 32 bytes length, if that xattr is not already present.