FAQ: macOS (Finder) Tags Mechanism and This App’s Implementation Details

1. What are macOS Finder Tags, and where are they stored?

Finder tags are part of a file’s metadata. They are not written into the file’s content itself but rather into the file’s extended attributes (xattr), primarily under the key:

• com.apple.metadata:_kMDItemUserTags

The value is a binary plist, essentially an array of tags. Each tag element contains a tag name and a color index, with color indices ranging from 0 to 7 (0: no color, 1: gray, 2: green, 3: purple, 4: blue, 5: yellow, 6: red, 7: orange).

Therefore:

• “Tagging a file” essentially means “writing tag metadata into xattr”;
• Whether the tags can be searched by Spotlight is a separate matter.

2. About the Legacy Extended Attribute com.apple.FinderInfo

com.apple.FinderInfo is one of the earlier mechanisms used by macOS/Finder:

• Old mechanism: It could only represent one color and did not include tag names.
• Still written by newer systems: Even though _kMDItemUserTags is now the primary standard, Finder may still write/update com.apple.FinderInfo simultaneously (for backward compatibility).

More specifically:

• Finder will only write/update the color information in com.apple.FinderInfo if a particular tag name exists in Finder’s custom tag list.
• When multiple colors are applied, it will record the color corresponding to the last tag in the active list.

3. Multilingual Issues: Why Does the Same Color Appear as “Different Tags” on Different Language Systems?

macOS writes localized tag name strings:

• On an English system, it writes Red.
• On a Chinese system, it writes 红色.

To the system, these are considered two distinct tags. This app retrieves default color tag names using system APIs, so the results depend on the system’s locale settings (“System Settings → General → Language & Region / Interface Language,” set to “Automatic” to follow the current system language). If the system language differs from the app’s language setting, inconsistent tag names may appear.

4. Why Should the App’s Settings Match Finder’s Tag Configuration?

• Due to macOS limitations, apps generally cannot fully read Finder’s “custom tag name ↔ color” configuration list.
• When reading tags, system APIs often return only the tag name without directly providing the color; if the app does not configure the corresponding color for that name, the displayed color may be incorrect.
• Similarly, when writing tags, system APIs usually pass only the tag name, and the final color is determined by Finder’s definition of that name.

5. How Is Tag Metadata Stored Across Different Disks and Network Locations? (APFS / AppleDouble / NTFS ADS)

5.1 APFS (Local Disk) — Native xattr Storage (Most Reliable)

APFS natively supports extended attributes, so tag metadata is stored directly within the file’s xattr.

5.2 Locations That Do Not Fully Support xattr — AppleDouble (._OriginalFileName)

When the target file system or protocol cannot reliably preserve xattr (commonly FAT32, exFAT, and network drives such as SMB/WebDAV/NFS), macOS stores the metadata in an AppleDouble companion file:

• ._OriginalFileName (e.g., photo.jpg corresponds to ._photo.jpg)

Visibility:

• Finder never displays these files, even if hidden files are shown.
• The terminal command ls -la will reveal them.
• Windows users can see them by enabling the display of hidden files, resulting in numerous small ._ files.

Important Note (A Common Cause of Lost Tags):

• If you move or copy files on Windows or through certain tools while only transferring the main file and leaving the ._ file behind, the tags will appear to “disappear” once the file reaches its new location.
• As long as the matching ._ file is also moved over, the tags can usually be restored.

5.3 SMB Connections to NTFS: Possible Use of ADS (Alternate Data Streams)

When accessing NTFS via SMB and under specific server/protocol configurations, macOS may bypass creating ._ files and instead write metadata into NTFS’s ADS (Alternate Data Streams):

• ADS is an NTFS feature: A file can have several “invisible additional data streams” alongside its main data, used to store extra metadata.
• Benefit: When moving or copying files within NTFS, this metadata is typically preserved, and the process remains relatively “clean” for Windows users (no ._ files are created).
• However:

• If you move or copy files from NTFS to FAT32 or exFAT, the destination file system does not support ADS/xattr-style metadata. Windows often prompts a message like:

“Are you sure you want to copy the file without copying its properties?” This indicates that the additional metadata will be discarded, and the tags may not survive the transfer.

6. How Can You View a File’s Tag xattr?

Using the command-line tool xattr is inconvenient: It does not handle or display com.apple.metadata:_kMDItemUserTags, which is a binary plist attribute. You must use the -px option to output it correctly in hexadecimal format.

It is recommended to use third-party tools:

• xattred: Allows you to visually inspect and verify xattrs such as _kMDItemUserTags and com.apple.FinderInfo.

7. What Is the Relationship Between Spotlight and Tags? Do Tags Depend on Spotlight?

• Tags themselves do not depend on Spotlight: Once you apply a tag, it is immediately written into the file’s xattr. Whether it gets indexed does not affect the tag’s existence.
• Spotlight is merely an indexing engine: It indexes tag names and other metadata to enable system-wide searching.
• macOS typically automatically maintains the index after operations like moving or renaming files; however, external disks, network drives, and directories added to “Search Privacy” may not be indexed by Spotlight.

8. What Does This App’s “Enhanced Indexing” Do?

When Spotlight cannot cover certain locations (external disks, network drives, privacy-excluded directories, etc.), this app provides enhanced indexing:

• While browsing folders in the app, it records the tags associated with files in that folder.
• When you select a specific tag from the directory tree to view all related files, the app supplements Spotlight’s search results with files matched by the enhanced index.
• You can right-click on a folder and choose “Scan and Update” to refresh the tag index for that folder’s contents.