3 of 21Quick Start Guide" 5Introduction" 5Installation and Setup" 6 List of All Files Installed by Tag Folders! 7Making Tag Folders " 8 Multi-word tags! 8 Spotlight comments! 8 Dropping ﬁles onto New Tag! 9Ways to Access and Use Tag Folders" 9Customizing a Tag Folder" 9 Basics of Tag Folder criteria! 10 Changing or adding tags and comments to an existing Tag Folder! 11 Keyword criteria! 11 Using other search criteria! 12 Automatically removing unwanted tags! 12 Including “Spotlight Items”! 12Hierarchical Tag Folders " 13Applying Extra Tags " 14Optional settings " 15 Update modiﬁcation times when tagging ﬁles! 15Growl Notiﬁcations " 16Tag Prompter" 16 Use! 16 Setup! 17
4 of 21 What you will be prompted to tag, and what you will not! 17 How it works! 17 What not to do! 18Comment to Tag Importer" 18Troubleshooting" 19Getting Support, Sharing Ideas, Etc." 20Non-English users" 20Source code, Licencing, and Modiﬁcations" 20
5 of 21Quick Start GuideRun the Tag Folders installer. Answer the setup questions, and then use “New Tag” tocreate new Tag Folders. Drag-and-drop ﬁles onto the icons of your Tag Folders in orderto tag them. Open a Tag Folder to see all the ﬁles that have that tag. Save a ﬁle into afolder that is being watched by Tag Prompter in order to be prompted to tag it.IntroductionTag Folders are Applescript droplets that automatically apply OpenMeta tags (and,optionally, Spotlight comments) to ﬁles based on the search criteria of a Smart Foldercontained inside each Tag Folder droplet. Opening a Tag Folder displays its SmartFolder, providing quick access to all ﬁles that have the associated tags.Thus, Tag Folders provide a simple, straightforward means of using Spotlight and SmartFolders to tag and organize ﬁles with minimal effort, using the familiar interface of theFinder.The advantage of Smart Folders over regular folders is clear: they bring together ﬁlesthat match certain conditions even though those ﬁles are actually scattered all over thehard drive. This means that one ﬁle can appear in any number of Smart Folders,allowing it to be grouped together with other ﬁles according to any set of criteria that theuser ﬁnds meaningful. The same ﬁle might appear in a Smart Folder for your trip toParis in 2004 (but not the return trip in 2007), in another Smart Folder for documentsand images related to Gothic architecture, and in another that gathers materials fromyour previous successful grant proposals.However, Smart Folders take more effort to set up than regular folders, and a simpledrag-and-drop does not allow a ﬁle to be moved from one group to another.An excellent solution to this limitation is the use of tags—small comments attached to aﬁle—to quickly designate any arbitrary groups that the ﬁle should belong to. Tag Foldersuses the OpenMeta tagging framework to create a simple, Finder-based, drag-and-dropmethod to apply tags quickly, easily, and automatically. Thus, Tag Folders are as easy touse as regular folders and as powerful as Smart Folders. They are what Smart Foldersshould have been.
6 of 21Installation and SetupTo install Tag Folders, run the Install Tag Folders application on the Tag Folders diskimage. It will place a copy of Tag Folders.app in your Applications folder, and then it willask you some setup questions.The ﬁrst question asks where to make the default folder in which new Tag Folders willbe created. (The folder does not have to stay here permanently, and can be moved to anew location at any time you like.) A Tag Folder called New Tag will automatically becreated inside this folder.The second question asks whether to run Tag Folders in legacy mode or in defaultmode. Legacy mode allows you to continue using older tagging applications that do notyet support OpenMeta tags. It is only necessary if you plan to keep using one of theseolder apps in the future. If you are no longer using a legacy tagging app, or if you havenever used one, it is recommended that you choose default mode. Default modeprovides extra functionality that is not available in Legacy mode.The third question asks what formatting to use with Spotlight Comments. There areseveral options available:• Spotlight default will simply write each word separated by spaces.• Natural Language separates each comment from the next using a comma and a space, as in normal English usage.• Users who have previously used other tagging applications to tag their ﬁles can maintain compatibility by selecting the appropriate formatting style from the list. Some of these options may ask for further information.• You may also choose to create a custom formatting style if the presets do not meet your needs. Custom formatting allows you to specify a custom comment delimiter (that is, the string of text used to separate one comment from the next) and/or a custom preﬁx and sufﬁx to attach to any comments. You will also be asked whether every word of a phrase should be formatted as a separate comment (e.g. “a”, “new”, “comment”), or if the phrase as a whole should be treated as one comment (e.g. “a new comment”).After you have answered these questions, the installer will update all your existing TagFolders to the latest version, and install all necessary support ﬁles.After this, Tag Prompter will launch and ask you its setup questions. Tag Prompterwatches folders for new or changed ﬁles, and prompts you to tag them automatically.Click the Add folders button to choose a folder to watch. You may repeat this process toadd as many folders as you like. To watch all the subfolders of a folder, or to stopwatching a folder, click the Edit folder list button. When you are ﬁnished, click Save andQuit. You may change these settings at any time by running the main Tag Foldersapplication from the Applications folder, and choosing “Conﬁgure Tag Prompter” fromthe pop up dialog box.
7 of 21Once you have answered these questions, you will be given the chance to create a newTag Folder. Select New Tag from the list and click OK. Follow the directions underMaking Tag Folders for help on how to make new Tag Folders.Finally, you will be asked to start the Comment to Tag Importer application. First it willask if you want to import the comments of all ﬁles, or only the ﬁles in a speciﬁc folder. Itwill then tell you how many ﬁles it has found to work on, and ask you how often it shouldpost progress notiﬁcations. Once you click the button to start the import, it will ask youfor the Spotlight comment format that you have used in the past, and then startimporting comments using those settings. You will receive progress notiﬁcations as theﬁles are processed, and a notiﬁcation when the import is complete. If any ﬁlesencountered errors during the import, they will be listed in an error log ﬁle on yourdesktop. You can manually tag these ﬁles yourself at any time. Finally, the Comment toTag Importer will run a check for illegal characters in the tags on your ﬁles, and offer toclean them up if found.List of All Files Installed by Tag FoldersWhen Tag Folders are installed on your computer, the following ﬁles and folders arecreated:1. /Applications/Tag Folders.app2. /Library/Spotlight/OpenMeta.mdimporter3. The default Tag Folders folder at a location you choose4. A Tag Folder named New Tag inside the default folder5. ~/Library/Application Support/Tag Folders6. ~/Library/Application Support/Tag Folders/Settings.plist7. ~/Library/Application Support/Tag Folders/Tag Folders (an alias to the default folder)8. ~/Library/Application Support/Tag Folders/Tag Selected Files.app9. ~/Library/Application Support/Tag Folders/Comment to Tag Importer.app10. ~/Library/Application Support/Tag Folders/Tag Prompter.app11. ~/Library/Application Support/Tag Folders/Tag Prompter Settings.plist12. ~/Library/LaunchAgents/com.vndv.tagfolders.tagprompter.plistIn addition, each Tag Folder that you make will create a corresponding Smart Folderinside ~/Library/Saved Searches.If you move a Tag Folder out of the default folder, when that Tag Folder is opened in itsnew location it will create an alias to itself inside the default folder. If you put the TagFolder back into the default folder and open it again, the alias will be deleted.NOTE: If Tag Folders is installed by a user without administrator privileges, items 1 and2 of this list will be installed to ~/Applications/Tag Folders.app and ~/Library/Spotlight/OpenMeta.mdimporter.
8 of 21Making Tag FoldersMaking new Tag Folders is very easy. Just double-click on the Tag Folder named NewTag and a small dialog box will pop up asking you to enter the text for the new tags touse for your new Tag Folder. If you want to use more than one tag for this Tag Folder,simply type more words.Once you have created a Tag Folder, you can modify it further. This is especially helpfulif you only want it to tag certain kinds of ﬁles, or if you want to create a Tag Folder thatremoves unwanted tags or comments. See Customizing a Tag Folder.Multi-word tagsNormally, each word becomes a tag. But sometimes two words really belong togetheras a single tag (“New York” rather than “New”, “York”). To create a multi-word tag in theNew Tag dialog box, enclose the words inside double quotation marks ( " ), like so:This example will create a Tag Folder with three tags: “New York”, “italian”, and“restaurant”.Spotlight commentsIf you are running Tag Folders in default mode, you will see a button labeled “AddSpotlight Comments…” in the New Tag dialog box. Legacy mode users will not see thisbutton. Click “Add Spotlight Comments…” to display a second dialog box where youmay enter some Spotlight Comments that you want this Tag Folder to search for and toapply to ﬁles.When entering Spotlight comments into the second dialog box, don’t include a tag preﬁxor sufﬁx. Just use the plain words themselves. If you have set Tag Folders to use tagpreﬁxes or sufﬁxes, they will be added for you automatically.
9 of 21Dropping ﬁles onto New TagIf you have a set of ﬁles that you want to make a new Tag Folder for, drag them onto theicon for New Tag. This will create a new Tag Folder as described above, with the addedbeneﬁt of automatically tagging the dropped ﬁles to match it.Ways to Access and Use Tag FoldersThere are several ways to access and use Tag Folders. By default, Tag Folders arestored inside a regular folder called “Tag Folders”. Opening this folder will giveimmediate access to all Tag Folders.However, Tag Folders may be kept anywhere you like. Aliases to Tag Folders in otherlocations will be made automatically in the default folder when the Tag Folders areopened. For example, you can put your favourite Tag Folder on your Desktop for easyaccess, and the ﬁrst time you open it from there, an alias to it will be made in the defaultfolder. This allows you to access your Tag Folder from the Desktop and from the defaultfolder.Because of this, adding the default folder to the Finder sidebar or as a Stack in the Dockwill give you quick access to all your Tag Folders, no matter where they are actuallystored.As an alternative, you can put the Tag Folders application in the Dock, the Findersidebar, or the Finder toolbar. Running the application will bring up a dialog box listingall your Tag Folders so you can either open them or add ﬁles to them. Adding the TagFolders application to the Finder toolbar makes it easy to tag ﬁles even faster than byusing drag-and-drop: if you have ﬁles selected in the Finder when you run theapplication, the list will offer to automatically add the selected ﬁles to whatever TagFolders you choose. If you have nothing selected, it will offer to open the chosen TagFolders instead.Finally, every Tag Folder will also have a corresponding Smart Folder stored in theSaved Searches folder of your user Library folder. This Smart Folder cannot apply tagsto ﬁles, but it will show all ﬁles that appear in the Tag Folder. Any modiﬁcations made tothe Tag Folder will immediately be reﬂected in this Smart Folder.Customizing a Tag Folder(Note: it is not recommended that you modify a Tag Folder after you start using it.Changing the criteria of a Tag Folder does not change the tags on the ﬁles it contains.The ﬁles will merely stop appearing in the Tag Folder because they no longer match itscriteria. Instead, make and modify a new Tag Folder, add all the ﬁles of your old TagFolder to the new Tag Folder, and then trash the old one. If you want to remove the oldtags from your ﬁles, use the trick described in Making a Tag Folder automaticallyremove unwanted tags below.)Every Tag Folder package contains a Smart Folder whose search criteria are used todetermine what tags it uses. Tag Folders may be changed by opening them and then
10 of 21modifying their search criteria. To do this, ﬁrst make sure the Action menu button isincluded in the Finder toolbar. (This can be done by control-clicking on the toolbar andselecting “Customize Toolbar….”) Then in the Tag Folder’s window, select Show SearchCriteria from the Action menu. This will show the current criteria used by the Tag Folder.Basics of Tag Folder criteriaWhen a new Tag Folder is created, you are asked to provide the text for one or moretags. The Tag Folder then simply looks for ﬁles that have those tags attached to them.However, a Tag Folder may be much more complex than that, using many differentsearch criteria. These complex Tag Folders can be created by modifying a newlygenerated Tag Folder to include these custom criteria.Figure 1Figure 1 shows an example of a complex Tag Folder. It ﬁnds all ﬁles that (1) have“example” in their tags or their keywords, (2) are PDFs, (3) either (a) have “urgent” intheir Spotlight comments or (b) were created this week and have “testing” in their tags,and (4) do not have “tag to remove” in their tags. If a PDF is dropped onto this TagFolder’s icon, it will be tagged with the tags “example” and “testing”, and also be given
11 of 21the Spotlight comment “urgent”. If the ﬁle has “tag to remove” in its tags, “tag to remove”will be removed from its tags.Changing or adding tags and comments to an existing Tag FolderTag are deﬁned using Tags criteria. The text box of a Tags criterion contains the text thatwill be used as the tag. There should be only one tag per criterion.Similarly, Spotlight comments are deﬁned using Spotlight comment criteria. The text boxof a Spotlight comment criterion contains the exact text that will be used as thecomment. This must include any preﬁx or sufﬁx used in your comment formatting style.It must not include the comment delimiter from your comment formatting style. Again,there should only be one comment per criterion.To change the tag or the comment that a Tag Folder uses, simply change the text in theTags criterion or the Spotlight comment criterion and click the Save button.To add a new tag to the Tag Folder, click on the (+) button and then choose “Other…”from the ﬁrst drop-down menu of the new criterion. After a few moments a dialog boxcontaining a large number of possible search criteria will open. Choose “Tags” and clickOK. (It is a good idea to check the “In Menu” checkbox next to “Tags” before clickingOK, so that tags criteria will be more easily available from now on.)To add a new Spotlight comment, follow the same method, but using “Spotlightcomment” in place of “Tags”.To make complex search criteria using Any, All, or None, hold down the Option key andclick on the (+) button next to an existing line of the search criteria. With the Option keypressed, the (+) button will change to a (…) button, allowing the insertion of Any, All, orNone criteria groups.NOTE: When using a Tags criterion, it is best to choose “is” from the second drop-downmenu. Using “matches” or “contains” may produce false positives, and the others mayfail to ﬁnd ﬁles that actually do have the desired tags. For example, “Tags matches foo”will ﬁnd all ﬁles with the tag “foo” but also all ﬁles with the tag “foobar”.On the other hand, for Spotlight comment criteria it is best to use “contains”. The reasonfor this is that whereas each OpenMeta tag exists as a separate entity, all the Spotlightcomments are mushed together into a single string of text. If “is” is used with a Spotlightcomment criterion, it will only ﬁnd ﬁles that have that word, and only that word, in theirSpotlight comments. Since it is likely that you will have several different words in thecomments of your ﬁle, it is best to use “contains”.Keyword criteriaBy default, a Tag Folder always searches for ﬁles that match its tags in either theirOpenMeta tags or in their keywords. As shown in Figure 1, this is accomplished byincluding both a Tags criterion and a Keywords criterion in an Any criteria group. It isgenerally a good idea to follow this method when customizing a Tag Folder.
12 of 21Unlike tags and comments, keywords cannot be written to a ﬁle that is dropped onto aTag Folder!s icon. Keywords are embedded into the ﬁle data itself, and cannot be editedwithout opening and editing the ﬁle.Using other search criteriaCriteria besides tags, comments, and keywords can also be included in your Tag Folder.In order for a ﬁle to be tagged by your Tag Folder, it must meet this other criteriaincluded. The basic rule of thumb here is that any ﬁle the Tag Folder could ﬁnd(assuming it had the right tags, comments, and/or keywords) is a ﬁle the Tag Folder cantag.For the example Tag Folder shown in Figure 1, only PDFs can be tagged with this TagFolder. A text document dropped onto this Tag Folder will be ignored. This is becauseonly PDFs can ever be found by this Tag Folder.On the other hand, even though there is a criterion looking for ﬁles created this week,this Tag Folder will tag a PDF of any age that dropped onto it. This is because of wherethe “Created date is this week” criterion is located in the logical structure of the TagFolder. Being created this week is part of only one possible way to satisfy the searchcriteria. Any PDF that had the tag “example” and and the Spotlight comment “urgent”would also satisfy the search criteria, so any PDF can be given the tags and commentsto let it do so.Automatically removing unwanted tagsIf you include a None criterion and put a tag or comment criterion beneath it, qualifyingﬁles dropped onto the Tag Folder will have that tag or comment removed from their listof tags.1 For the example Tag Folder shown in Figure 1, any PDF that is dropped ontothe Tag Folder’s icon will have the tag “tag to remove” removed from its tags. Thisfeature can be especially helpful if you want to get rid of a certain tag from a largenumber of ﬁles with a minimal amount of work.Including “Spotlight Items”As of version 1.3, Tag Folders include “Spotlight Items” by default. Spotlight Itemsinclude human readable representations of iCal events, Address Book contacts, andemail messages. Including Spotlight Items in the search criteria of a Tag Folder makes iteasy to tag these items and to display them in a Tag Folder when it is opened.To make best use of this feature, you will typically have to do a search in the Spotlightmenu for the item you want to tag, and then select Show All in the menu to open a1However, double negatives are respected in making this decision. If a None criterion contains anotherNone criterion that contains a tags criterion, the tag in that criterion will be applied to ﬁles.
13 of 21Finder window displaying the search results.2 You can then drag the desired item onto aTag Folder to tag them. It will appear in the Tag Folder from then on.Unfortunately it is not possible to drag an email, iCal item, or contact directly from Mail,iCal, or Address Book onto a Tag Folder. However, in Address Book you can right-clickon a contact and choose the Spotlight option from the contextual menu to quickly opena Finder search window from which you can tag the contact (and any other ﬁlesconnected with that contact). In combination with keyword search criteria (see above),MailTags can make it easy to add email messages to a Tag Folder without having toleave the Mail.app interface. Just use MailTags to tag an email with a keyword thatmatches a Tag Folder, and the email will appear in that Tag Folder next time you open it.If you do not want to include Spotlight items in a Tag Folder, you can simply remove theSpotlight Item search criterion from the Tag Folder’s criteria.Hierarchical Tag FoldersTag Folders can contain other Tag Folders, and ﬁles added to a child Tag Folder alsoinherit the tags and comments of the parent Tag Folder.Suppose you have a Tag Folder that searches for the tag “Project 1” and another thatsearches for the tag “Work”. If you drop the “Project 1” Tag Folder onto the “Work” TagFolder, it will become a child of “Work” and will appear as an item inside the “Work” TagFolder. This is very similar to the way regular folders work, with one folder nested insideanother to create a hierarchy, except that the Tag Folders can also exist side by side orin entirely different locations. Moreover, a Tag Folder can have more than one parent,allowing it to appear in a number of other Tag Folders.Files added to a child Tag Folder have that Tag Folder’s tags applied to it, as well as thetags of the parent Tag Folder(s). Once “Project 1” has been added to “Work”, any ﬁlesadded to “Project 1” will be tagged with the tags that “Project 1” applies, and also withthe tags that “Work” applies. Under normal circumstances, this means that the ﬁle willnow appear inside both “Project 1” and “Work”.There are some situations in which a ﬁle added to a child Tag Folder might not appearin a parent Tag Folder:1. If you have already begun tagging ﬁles with a Tag Folder before you make that Tag Folder the child of another Tag Folder, the ﬁles you previously tagged will not be added to the parent Tag Folder automatically.2 For example, to add Tom Thumb’s contact information to a Tag Folder about a 2008 project proposal,search in the Spotlight menu for “Tom Thumb kind:contact”. To ﬁnd some key email messages youexchanged with Tom Thumb about the proposal, search for “Tom Thumb 2008 proposal kind:mail”. Notethat you do not need to include the “kind:” part of the search, since all kinds are included by default, butdoing so will help narrow down the results you get.
14 of 212. If a ﬁle bears a tag that has been excluded from the parent Tag Folder3 but has not been excluded from the child Tag Folder, adding the ﬁle to the child Tag Folder will not make it appear in the parent Tag Folder.3. If the parent Tag Folder includes other kinds of search criteria besides tag, comment, or keyword criteria,4 the ﬁle will only appear there if it matches those additional search criteria.The ﬁrst two of these situations can be addressed by selecting the ﬁles of the child TagFolder and dropping them onto the icon of the parent Tag Folder.Applying Extra TagsAside from the tags used in a Tag Folder’s search criteria, extra tags may also beapplied to ﬁles dropped onto a Tag Folder. This is useful if, for example, you want yourTag Folder to show you all ﬁles with the tag “French Revolution”, but to tag ﬁles withboth “French Revolution” and “research”.The mechanism to do this is very simple: apply tags or comments to the Tag Folderitself.To apply extra tags and comments to a Tag Folder, all you need to do is drag your TagFolder onto New Tag, enter the desired tags and/or comments in the New Tag dialogbox, and click OK. This will apply the tags to your existing Tag Folder, and also create asecond Tag Folder that searches for those tags. You may safely delete the second TagFolder if you don!t need it: the original Tag Folder will keep its tags even if the secondone is deleted.5Alternatively, you can apply tags to a Tag Folder using any other OpenMeta taggingapplication. You can also apply extra Spotlight comments directly to a Tag Folder byselecting it in Finder, choosing Get Info from the File menu, and then typing thecomments into the Spotlight comments section of the Info palette.(Note that any text entered in the Spotlight comments of a Tag Folder will be appliedwithout alteration6 to all ﬁles dropped onto the Tag Folder’s icon. If you set Tag Foldersto attach a preﬁx or sufﬁx to your comments, make sure to include them in anycomments you enter here.)3 See Automatically removing unwanted tags above.4 See Using other search criteria above.5Astute readers will notice that this is the basically same method that is used to create hierarchical TagFolders, except that you are then throwing away the parent Tag Folder.6Except in the case of Punakea formatted comments. If the user chooses Punakea compatibility whensetting up Tag Folders, any Punakea formatted comments added to a Tag Folder’s Spotlight commentswill be parsed and processed in order to properly apply them to ﬁles. However, even in this case anySpotlight comments that are not in Punakea format will be passed on to tagged ﬁles without alteration.
15 of 21Note that if you have already tagged some ﬁles with a Tag Folder, and you then addextra tags or comments to the Tag Folder, those extra tags and comments are notautomatically applied to previously tagged ﬁles. To update the previously tagged ﬁleswith the new tags, re-add them to the Tag Folder.Optional settingsUpdate modiﬁcation times when tagging ﬁlesNormally, when you tag a ﬁle its modiﬁcation time is not changed. No data inside the ﬁleitself has been changed in any way, so OS X does not consider the ﬁle to have beenmodiﬁed. In normal use this is the desired behavior. It is not recommended that youupdate modiﬁcation times when tagging ﬁles unless you really, really need to.Turning on this feature will cause backup software such as Time Machine to makeunnecessary backups of your tagged ﬁles every time a tag or comment changes onthem, and so will end up consuming lots of disk space for no good reason. This is notnecessary, because the OpenMeta framework has a transparent tag backup systemalready in place so that your tags are automatically backed up and restored to your ﬁleswithout having to back up the entire ﬁle along with the tags that are attached to it.However, some users may have a situation where they need to change this behavior.For example, some users may use ﬁle synchronization applications that do not properlysupport syncing extended attributes (such as tags and Spotlight comments). Some, butnot all, syncing applications may be helped by updating the modiﬁcation times of taggedﬁles. The best solution is to upgrade to a syncing app that does handle them properly(see below for a list of good ones). But if that is not an option, some users may havesuccess syncing their tags by telling Tag Folders to update the modiﬁcation time of a ﬁlewhen tagging it.To activate this feature, you will need to edit the ﬁle ~/Library/Application Support/TagFolders/Settings.plist. Depending on your computer, this ﬁle might open in TextEdit or inProperty List Editor when you double-click on it. In TextEdit, search for the line that says“<key>update_modiﬁcation_time</key>”, and then change the next line from “<false/>”to “<true/>”. In Property List Editor, click on the triangle next to “Root” to show the list ofsettings, and then change the value of “update_modiﬁcation_time” from “No” to “Yes”.Settings.plist also provides an option to update the access time of a ﬁle (using thesetting called update_access_time). It is unlikely that this option will ever be useful toanyone, but it is there if you need it.Note that some syncing applications do not support extended attributes (such as tagsand Spotlight comments) at all. For these apps, updating the modiﬁcation time of a ﬁlewill not help in any way. This option is only useful for syncing apps that are able to syncthe extended attributes, but do not check the extended attributes when decidingwhether or not to sync the ﬁle in the ﬁrst place.
16 of 21A better way to sync your ﬁles, including the tags, is to use a syncing app that fullysupports extended attributes:• If you are a MobileMe subscriber ($99/yr), your iDisk should handle this effortlessly and just as you would expect.• ChronoSync ($40) does well with synchronizing tags and Spotlight comments along with the ﬁles themselves. Just make sure that ChronoSync is conﬁgured to preserve extended attributes and to sync invisible ﬁles.• The command line tool rsync, which is included with OS X, is able to preserve tags and Spotlight comments properly when used with the -E option.7 Rsync only syncs in one direction, so if you need two-way syncing, consider Unison instead. Many easy-to- use synchronization applications are available that are based on rsync.• Unison (free) does full bidirectional syncing, with full support for extended attributes enabled by default when syncing between OS X clients. It has a GUI and a command line interface.Growl NotiﬁcationsAs of version 1.1, Tag Folders can provide Growl notiﬁcations when ﬁles are tagged.Progress reports via Growl can also be displayed when tagging a large number of ﬁlesat once. Growl notiﬁcations are conﬁgured using the Growl preference pane in SystemPreferences.Tag PrompterTag Prompter is a helper application that assists you in keeping the tags on your ﬁles upto date. It watches folders for new or modiﬁed ﬁles and prompts you to tag themautomatically. This advancement makes it almost effortless to keep your ﬁles properlytagged and organized and to avoid the otherwise inevitable accumulation of forgotten,untagged ﬁles.UseSuppose you are working on a new document, and after making some good progressyou save the document to your Documents folder. With Tag Prompter watching yourDocuments folder, a dialog box will appear within a moment or two offering to tag thatdocument by adding it to any Tag Folders you choose. Aside from selecting theappropriate Tag Folder(s) from the list, no further work on your part is needed.7Type man rsync in Terminal to see the user manual for rsync. The key option for preserving Spotlightcomments with the version of rsync included with Leopard is the !E option. For rsync version 3.0 or later,use !X instead of !E
17 of 21SetupTag Prompter can watch whatever folders you choose. To quickly add folders to the listof folders that Tag Prompter watches, simply drag-and-drop them onto the main TagFolders application icon (located in your Applications folder by default). You will beasked whether you want to start watching the folders for changes.For more control over the list of watched folders, run the main Tag Folders applicationand select “Conﬁgure Tag Prompter” from the startup dialog. This will start the TagPrompter conﬁguration applet that allows you to add or remove folders from the watchlist. The “Add folders” button allows you to select new folders to watch. Use the “Editfolder list” button to stop watching a folder or to start watching a folder’s subfolders.When you are done choosing what folders you want Tag Prompter to watch forchanges, click the “Save and quit” button. You may reconﬁgure Tag Prompter again atany time to change your settings.The Tag Prompter applet is stored in the Tag Folders application support folder. Do notmove it from this location, or it will stop working.What you will be prompted to tag, and what you will notFirst, Tag Prompter will only prompt you to tag ﬁles that do not have anything written intheir Spotlight comments. If you have already tagged a ﬁle and then make changes to it,Tag Prompter will not bother you about it.Second, Tag Prompter only prompts you to tag ﬁles. It will not prompt you to add tags tofolders you create. If you want to tag a folder you will have to do so by the usualmethods.If you tell Tag Prompter to watch all the subfolders of a folder and then later make a newfolder somewhere inside that folder, you will be asked whether you want to startwatching the new folder as well. For example, suppose I have a folder called Work thatcontains three subfolders, Project 1, Project 2, and Project 3, and I tell Tag Prompter towatch Work and all its subfolders. If I then create a new folder called Estimate insideProject 1, Tag Prompter will pop up and ask me if I would like to start watching Estimatefor changes.How it worksTag Prompter uses OS X’s built-in technologies to provide its services. The actualwatching is done by the operating system itself using a “launch agent.” Launch agentsare used by the operating system to perform all sorts of tasks. By using a launch agent,Tag Prompter can run continuously while using almost no resources on your computerat all.The launch agent called com.vndv.tagfolders.tagprompter watches the folders youchoose for changes. When a change is detected by the launch agent, one of TagPrompter’s Applescripts is called to determine whether or not to prompt you to tag thenew/changed ﬁle(s).
18 of 21However, when a launch agent watches a folder, it only looks down one layer deep: if aﬁle changes in a subfolder of the watched folder, you will not be prompted to tag it. Towatch the contents of the subfolder, you must add the subfolder to the list of watchedfolders.What not to doDo not go crazy watching subfolders! It is a bad idea, for example, to tell Tag Prompterto watch all the subfolders of your home folder. First, you really don’t want to beprompted to tag every little ﬁle that ever changes in the bowels of your Library folder.Second, although I worked hard to make Tag Prompter as quick as possible, sortingthrough thousands upon thousands of unnecessary items will slow it down.It is also a bad idea to tell Tag Prompter to watch your iTunes library, the contents ofyour iPhoto library, etc. Applications like these already have built-in systems formanaging ﬁles (including tagging with keywords), and their data should be left alone.I recommend watching your Documents folder, perhaps your Desktop folder, and anyother folders that you actively use on a regular basis. Leave those dusty old long-termstorage folders off the list; watching them will only slow things down for no real gain.Comment to Tag ImporterTag Folders 2.0 includes an importer applet that can import Spotlight comments intoOpenMeta tags. This importer runs once at the end of the installation of Tag Folders,and can be run again at any time by selecting “Import Spotlight comments” from thestartup dialog of the main Tag Folders app.You may either import the comments of all ﬁles on your computer, or the ﬁles in a folderyou choose.You will be informed of how many ﬁles there are to be imported, and asked how often todisplay progress notiﬁcations.Finally, you will be asked for the formatting system you used on your existing Spotlightcomments. Since this may not be the same as what you told Tag Folders to use forformatting your current comments, you have to deﬁne it again here.The importer will then copy over all the Spotlight comments of your ﬁles into OpenMetatags. Progress notiﬁcations will be displayed at the frequency you speciﬁed.When the import is complete, you will be informed if there were any ﬁles whosecomments could not be imported. If there were any such ﬁles, a list of them will becreated on your desktop in a ﬁle called Spotlight comment import error log.txt.Finally, the importer will double check that there are no illegal characters in theOpenMeta tags, and will clean them up if there are.
19 of 21TroubleshootingIf your Tag Folders do not behave as expected, there are a few things you can try.1. Make sure the ﬁle you want to tag meets the criteria of your Tag Folder. If you cannot tag a ﬁle with a particular Tag Folder, check whether the Tag Folder has been set to accept only certain ﬁles and whether your ﬁle meets those criteria. To add your ﬁle, you will need to either change it to match the criteria of the Tag Folder, or change the criteria of the Tag Folder to allow the ﬁle.2. Reinstall Tag Folders. This can address a wide variety of problems.3. If Tag Prompter doesn!t seem to do anything: i. Make sure the ﬁles you want to be prompted for do not already have something written in their OpenMeta tags or their Spotlight Comments, and are not folders. Tag Prompter will not prompt you to tag either of these. If you want to add, remove, or change the tags on such a ﬁle or folder, drop it onto the icon of a Tag Folder. ii. Use Terminal to make sure Tag Prompter is running. Open Terminal and type launchctl list | grep tagprompter at the command prompt. If Tag Prompter is running properly, the result should say - 0 com.vndv.tagfolders.tagprompter or something like 4895 - com.vndv.tagfolders.tagprompter In the ﬁrst example, Tag Prompter is running normally, but currently has nothing to work on. If the result contains a 1 instead of a 0 in the second column, Tag Prompter is running, but is encountering an error. In the second example, Tag Prompter is actively processing a ﬁle and probably waiting for you to give it an answer to a question. Note that in the second example, the number in the ﬁrst column will be different every time. If nothing comes back as a result of this command, select “Conﬁgure Tag Prompter” from the Tag Folders.app startup dialog in order to restart Tag Prompter. After clicking the Save and Quit button, check again in Terminal again.4. Rebuild the Spotlight database. Tag Folders and Tag Prompter are highly dependent on the database Spotlight maintains of the ﬁles on your computer. If there is any corruption of the Spotlight database, Tag Folders and Tag Prompter may not
20 of 21 be able to work as intended. Instructions on how to rebuild the Spotlight database can be found here.5. If none of the above works, open the script contained inside the application bundle using Script Editor and run it that way to ﬁnd out what errors might be happening. Control-click on the application in question, choose Show Package Contents from the contextual menu, and then navigate to Contents/Resources/ Scripts. Tag Folders only contain one script. Tag Prompter contains two: main.scpt runs the setup functions, and TagPrompterScript.scpt analyzes ﬁles to decide whether to prompt you. Choose the appropriate script to test, open it, and run it using the big green run button in Script Editor. If the script encounters any errors, it will notify you about them. If you know how to ﬁx this yourself, please do so and then contact me by posting on the Tag Folders Google Group so I can update the software for everyone. If not, please post on the Tag Folders Google Group with the error report so I can work on a ﬁx.Getting Support, Sharing Ideas, Etc.Tag Folders is freeware, and I actually do something entirely different from softwaredevelopment with most of my time. So I promise you nothing. That said, I like beinghelpful, and there are lots of other people in the world who like being helpful too. If youwant to talk about Tag Folders, report a bug, get some help, or share an idea, the bestway to do that is to go to the Tag Folders Google Group at http://groups.google.com/group/tag-folders. There you can post messages to me and other readers.Non-English usersTag Folders version 1.2 and higher should work with all language settings on Mac OS X.However, Tag Folders currently only has English dialog box messages. If you would liketo help translate the Tag Folders interface into your language, please contact me byposting on the Tag Folders Google Group.In earlier versions of Tag Folders, non-English users sometimes received errors due toEnglish speciﬁc terms, and had to modify the Tag Folders source code. This should nolonger be the case.Source code, Licencing, and ModiﬁcationsTag Folders.app, Tag Prompter.app, and Comment to Tags Importer.app are distributedunder the GPL 3.0 licence. A copy of the licence is included inside the applicationbundle of every Tag Folder, and inside the application bundle of Tag Prompter.app andComment to Tags Importer.app. The source code for Tag Folders can be accessed byopening Contents/Resources/Scripts/main.scpt inside the application bundle of any TagFolder. The source code for Tag Prompter can be accessed by opening the .scpt ﬁles inContents/Resources/Scripts/ inside the application bundle of Tag Prompter. The sourcecode for Comment to Tags Importer can be accessed by opening Contents/Resources/Scripts/main.scpt inside the application bundle of Comment to Tags Importer.app. If youmake any improvements to the source code of Tag Folders or Tag Prompter and believe
21 of 21they may be beneﬁcial to others, please consider submitting them to the Tag Foldersproject by posting on the Tag Folders Google Group. The Tag Folders icon is based onan icon created by Jonathan Hunt at iconaholic.com, and is used by permission, withmany thanks.