You are on page 1of 21

Tag Folders

User!s Guide
Version 2.0
2 of 21

© 2008 Jon Christian Stovell This work is licensed under the Creative Commons
Attribution-Noncommercial-Share Alike 2.5 Canada Licence. To view a copy of this
licence, send a letter to Creative Commons, 171 2nd Street, Suite 300, San Francisco,
California, 94105, USA, or visit http://creativecommons.org/licenses/by-nc-sa/2.5/ca/
3 of 21

Quick Start Guide" 5

Introduction" 5

Installation and Setup" 6


List of All Files Installed by Tag Folders! 7

Making Tag Folders " 8


Multi-word tags! 8

Spotlight comments! 8

Dropping files onto New Tag! 9

Ways to Access and Use Tag Folders" 9

Customizing 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”! 12

Hierarchical Tag Folders " 13

Applying Extra Tags " 14

Optional settings " 15


Update modification times when tagging files! 15

Growl Notifications " 16

Tag 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! 18

Comment to Tag Importer" 18

Troubleshooting" 19

Getting Support, Sharing Ideas, Etc." 20

Non-English users" 20

Source code, Licencing, and Modifications" 20


5 of 21

Quick Start Guide


Run the Tag Folders installer. Answer the setup questions, and then use “New Tag” to
create new Tag Folders. Drag-and-drop files onto the icons of your Tag Folders in order
to tag them. Open a Tag Folder to see all the files that have that tag. Save a file into a
folder that is being watched by Tag Prompter in order to be prompted to tag it.

Introduction
Tag Folders are Applescript droplets that automatically apply OpenMeta tags (and,
optionally, Spotlight comments) to files based on the search criteria of a Smart Folder
contained inside each Tag Folder droplet. Opening a Tag Folder displays its Smart
Folder, providing quick access to all files that have the associated tags.

Thus, Tag Folders provide a simple, straightforward means of using Spotlight and Smart
Folders to tag and organize files with minimal effort, using the familiar interface of the
Finder.

The advantage of Smart Folders over regular folders is clear: they bring together files
that match certain conditions even though those files are actually scattered all over the
hard drive. This means that one file can appear in any number of Smart Folders,
allowing it to be grouped together with other files according to any set of criteria that the
user finds meaningful. The same file might appear in a Smart Folder for your trip to
Paris in 2004 (but not the return trip in 2007), in another Smart Folder for documents
and images related to Gothic architecture, and in another that gathers materials from
your previous successful grant proposals.

However, Smart Folders take more effort to set up than regular folders, and a simple
drag-and-drop does not allow a file to be moved from one group to another.

An excellent solution to this limitation is the use of tags—small comments attached to a


file—to quickly designate any arbitrary groups that the file should belong to. Tag Folders
uses the OpenMeta tagging framework to create a simple, Finder-based, drag-and-drop
method to apply tags quickly, easily, and automatically. Thus, Tag Folders are as easy to
use as regular folders and as powerful as Smart Folders. They are what Smart Folders
should have been.
6 of 21

Installation and Setup


To install Tag Folders, run the Install Tag Folders application on the Tag Folders disk
image. It will place a copy of Tag Folders.app in your Applications folder, and then it will
ask you some setup questions.

The first question asks where to make the default folder in which new Tag Folders will
be created. (The folder does not have to stay here permanently, and can be moved to a
new location at any time you like.) A Tag Folder called New Tag will automatically be
created inside this folder.

The second question asks whether to run Tag Folders in legacy mode or in default
mode. Legacy mode allows you to continue using older tagging applications that do not
yet support OpenMeta tags. It is only necessary if you plan to keep using one of these
older apps in the future. If you are no longer using a legacy tagging app, or if you have
never used one, it is recommended that you choose default mode. Default mode
provides extra functionality that is not available in Legacy mode.

The third question asks what formatting to use with Spotlight Comments. There are
several 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 files 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
prefix and suffix 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 Tag
Folders to the latest version, and install all necessary support files.

After this, Tag Prompter will launch and ask you its setup questions. Tag Prompter
watches folders for new or changed files, and prompts you to tag them automatically.
Click the Add folders button to choose a folder to watch. You may repeat this process to
add as many folders as you like. To watch all the subfolders of a folder, or to stop
watching a folder, click the Edit folder list button. When you are finished, click Save and
Quit. You may change these settings at any time by running the main Tag Folders
application from the Applications folder, and choosing “Configure Tag Prompter” from
the pop up dialog box.
7 of 21

Once you have answered these questions, you will be given the chance to create a new
Tag Folder. Select New Tag from the list and click OK. Follow the directions under
Making 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 will
ask if you want to import the comments of all files, or only the files in a specific folder. It
will then tell you how many files it has found to work on, and ask you how often it should
post progress notifications. Once you click the button to start the import, it will ask you
for the Spotlight comment format that you have used in the past, and then start
importing comments using those settings. You will receive progress notifications as the
files are processed, and a notification when the import is complete. If any files
encountered errors during the import, they will be listed in an error log file on your
desktop. You can manually tag these files yourself at any time. Finally, the Comment to
Tag Importer will run a check for illegal characters in the tags on your files, and offer to
clean them up if found.

List of All Files Installed by Tag Folders


When Tag Folders are installed on your computer, the following files and folders are
created:

1. /Applications/Tag Folders.app
2. /Library/Spotlight/OpenMeta.mdimporter
3. The default Tag Folders folder at a location you choose
4. A Tag Folder named New Tag inside the default folder
5. ~/Library/Application Support/Tag Folders
6. ~/Library/Application Support/Tag Folders/Settings.plist
7. ~/Library/Application Support/Tag Folders/Tag Folders (an alias to the default folder)
8. ~/Library/Application Support/Tag Folders/Tag Selected Files.app
9. ~/Library/Application Support/Tag Folders/Comment to Tag Importer.app
10. ~/Library/Application Support/Tag Folders/Tag Prompter.app
11. ~/Library/Application Support/Tag Folders/Tag Prompter Settings.plist
12. ~/Library/LaunchAgents/com.vndv.tagfolders.tagprompter.plist

In addition, each Tag Folder that you make will create a corresponding Smart Folder
inside ~/Library/Saved Searches.

If you move a Tag Folder out of the default folder, when that Tag Folder is opened in its
new location it will create an alias to itself inside the default folder. If you put the Tag
Folder 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 and
2 of this list will be installed to ~/Applications/Tag Folders.app and ~/Library/Spotlight/
OpenMeta.mdimporter.
8 of 21

Making Tag Folders


Making new Tag Folders is very easy. Just double-click on the Tag Folder named New
Tag and a small dialog box will pop up asking you to enter the text for the new tags to
use 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 helpful
if you only want it to tag certain kinds of files, or if you want to create a Tag Folder that
removes unwanted tags or comments. See Customizing a Tag Folder.

Multi-word tags
Normally, each word becomes a tag. But sometimes two words really belong together
as a single tag (“New York” rather than “New”, “York”). To create a multi-word tag in the
New 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 comments
If you are running Tag Folders in default mode, you will see a button labeled “Add
Spotlight Comments…” in the New Tag dialog box. Legacy mode users will not see this
button. Click “Add Spotlight Comments…” to display a second dialog box where you
may enter some Spotlight Comments that you want this Tag Folder to search for and to
apply to files.

When entering Spotlight comments into the second dialog box, don’t include a tag prefix
or suffix. Just use the plain words themselves. If you have set Tag Folders to use tag
prefixes or suffixes, they will be added for you automatically.
9 of 21

Dropping files onto New Tag


If you have a set of files that you want to make a new Tag Folder for, drag them onto the
icon for New Tag. This will create a new Tag Folder as described above, with the added
benefit of automatically tagging the dropped files to match it.

Ways to Access and Use Tag Folders


There are several ways to access and use Tag Folders. By default, Tag Folders are
stored inside a regular folder called “Tag Folders”. Opening this folder will give
immediate access to all Tag Folders.

However, Tag Folders may be kept anywhere you like. Aliases to Tag Folders in other
locations will be made automatically in the default folder when the Tag Folders are
opened. For example, you can put your favourite Tag Folder on your Desktop for easy
access, and the first time you open it from there, an alias to it will be made in the default
folder. This allows you to access your Tag Folder from the Desktop and from the default
folder.

Because of this, adding the default folder to the Finder sidebar or as a Stack in the Dock
will give you quick access to all your Tag Folders, no matter where they are actually
stored.

As an alternative, you can put the Tag Folders application in the Dock, the Finder
sidebar, or the Finder toolbar. Running the application will bring up a dialog box listing
all your Tag Folders so you can either open them or add files to them. Adding the Tag
Folders application to the Finder toolbar makes it easy to tag files even faster than by
using drag-and-drop: if you have files selected in the Finder when you run the
application, the list will offer to automatically add the selected files to whatever Tag
Folders you choose. If you have nothing selected, it will offer to open the chosen Tag
Folders instead.

Finally, every Tag Folder will also have a corresponding Smart Folder stored in the
Saved Searches folder of your user Library folder. This Smart Folder cannot apply tags
to files, but it will show all files that appear in the Tag Folder. Any modifications made to
the Tag Folder will immediately be reflected 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 files it contains.
The files will merely stop appearing in the Tag Folder because they no longer match its
criteria. Instead, make and modify a new Tag Folder, add all the files of your old Tag
Folder to the new Tag Folder, and then trash the old one. If you want to remove the old
tags from your files, use the trick described in Making a Tag Folder automatically
remove unwanted tags below.)

Every Tag Folder package contains a Smart Folder whose search criteria are used to
determine what tags it uses. Tag Folders may be changed by opening them and then
10 of 21

modifying their search criteria. To do this, first make sure the Action menu button is
included in the Finder toolbar. (This can be done by control-clicking on the toolbar and
selecting “Customize Toolbar….”) Then in the Tag Folder’s window, select Show Search
Criteria from the Action menu. This will show the current criteria used by the Tag Folder.

Basics of Tag Folder criteria


When a new Tag Folder is created, you are asked to provide the text for one or more
tags. The Tag Folder then simply looks for files that have those tags attached to them.

However, a Tag Folder may be much more complex than that, using many different
search criteria. These complex Tag Folders can be created by modifying a newly
generated Tag Folder to include these custom criteria.

Figure 1

Figure 1 shows an example of a complex Tag Folder. It finds all files that (1) have
“example” in their tags or their keywords, (2) are PDFs, (3) either (a) have “urgent” in
their 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 Tag
Folder’s icon, it will be tagged with the tags “example” and “testing”, and also be given
11 of 21

the Spotlight comment “urgent”. If the file 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 Folder


Tag are defined using Tags criteria. The text box of a Tags criterion contains the text that
will be used as the tag. There should be only one tag per criterion.

Similarly, Spotlight comments are defined using Spotlight comment criteria. The text box
of a Spotlight comment criterion contains the exact text that will be used as the
comment. This must include any prefix or suffix 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 the
Tags 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 first drop-down menu of the new criterion. After a few moments a dialog box
containing a large number of possible search criteria will open. Choose “Tags” and click
OK. (It is a good idea to check the “In Menu” checkbox next to “Tags” before clicking
OK, so that tags criteria will be more easily available from now on.)

To add a new Spotlight comment, follow the same method, but using “Spotlight
comment” in place of “Tags”.

To make complex search criteria using Any, All, or None, hold down the Option key and
click on the (+) button next to an existing line of the search criteria. With the Option key
pressed, the (+) button will change to a (…) button, allowing the insertion of Any, All, or
None criteria groups.

NOTE: When using a Tags criterion, it is best to choose “is” from the second drop-down
menu. Using “matches” or “contains” may produce false positives, and the others may
fail to find files that actually do have the desired tags. For example, “Tags matches foo”
will find all files with the tag “foo” but also all files with the tag “foobar”.

On the other hand, for Spotlight comment criteria it is best to use “contains”. The reason
for this is that whereas each OpenMeta tag exists as a separate entity, all the Spotlight
comments are mushed together into a single string of text. If “is” is used with a Spotlight
comment criterion, it will only find files that have that word, and only that word, in their
Spotlight comments. Since it is likely that you will have several different words in the
comments of your file, it is best to use “contains”.

Keyword criteria
By default, a Tag Folder always searches for files that match its tags in either their
OpenMeta tags or in their keywords. As shown in Figure 1, this is accomplished by
including both a Tags criterion and a Keywords criterion in an Any criteria group. It is
generally a good idea to follow this method when customizing a Tag Folder.
12 of 21

Unlike tags and comments, keywords cannot be written to a file that is dropped onto a
Tag Folder!s icon. Keywords are embedded into the file data itself, and cannot be edited
without opening and editing the file.

Using other search criteria


Criteria besides tags, comments, and keywords can also be included in your Tag Folder.
In order for a file to be tagged by your Tag Folder, it must meet this other criteria
included. The basic rule of thumb here is that any file the Tag Folder could find
(assuming it had the right tags, comments, and/or keywords) is a file the Tag Folder can
tag.

For the example Tag Folder shown in Figure 1, only PDFs can be tagged with this Tag
Folder. A text document dropped onto this Tag Folder will be ignored. This is because
only PDFs can ever be found by this Tag Folder.

On the other hand, even though there is a criterion looking for files created this week,
this Tag Folder will tag a PDF of any age that dropped onto it. This is because of where
the “Created date is this week” criterion is located in the logical structure of the Tag
Folder. Being created this week is part of only one possible way to satisfy the search
criteria. 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 comments
to let it do so.

Automatically removing unwanted tags


If you include a None criterion and put a tag or comment criterion beneath it, qualifying
files dropped onto the Tag Folder will have that tag or comment removed from their list
of tags.1 For the example Tag Folder shown in Figure 1, any PDF that is dropped onto
the Tag Folder’s icon will have the tag “tag to remove” removed from its tags. This
feature can be especially helpful if you want to get rid of a certain tag from a large
number of files with a minimal amount of work.

Including “Spotlight Items”


As of version 1.3, Tag Folders include “Spotlight Items” by default. Spotlight Items
include human readable representations of iCal events, Address Book contacts, and
email messages. Including Spotlight Items in the search criteria of a Tag Folder makes it
easy 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 Spotlight
menu for the item you want to tag, and then select Show All in the menu to open a

1However, double negatives are respected in making this decision. If a None criterion contains another
None criterion that contains a tags criterion, the tag in that criterion will be applied to files.
13 of 21

Finder window displaying the search results.2 You can then drag the desired item onto a
Tag 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-click
on a contact and choose the Spotlight option from the contextual menu to quickly open
a Finder search window from which you can tag the contact (and any other files
connected 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 to
leave the Mail.app interface. Just use MailTags to tag an email with a keyword that
matches 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 the
Spotlight Item search criterion from the Tag Folder’s criteria.

Hierarchical Tag Folders


Tag Folders can contain other Tag Folders, and files added to a child Tag Folder also
inherit the tags and comments of the parent Tag Folder.

Suppose you have a Tag Folder that searches for the tag “Project 1” and another that
searches for the tag “Work”. If you drop the “Project 1” Tag Folder onto the “Work” Tag
Folder, it will become a child of “Work” and will appear as an item inside the “Work” Tag
Folder. This is very similar to the way regular folders work, with one folder nested inside
another to create a hierarchy, except that the Tag Folders can also exist side by side or
in 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 the
tags of the parent Tag Folder(s). Once “Project 1” has been added to “Work”, any files
added to “Project 1” will be tagged with the tags that “Project 1” applies, and also with
the tags that “Work” applies. Under normal circumstances, this means that the file will
now appear inside both “Project 1” and “Work”.

There are some situations in which a file added to a child Tag Folder might not appear
in a parent Tag Folder:

1. If you have already begun tagging files with a Tag Folder before you make that Tag
Folder the child of another Tag Folder, the files 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 find some key email messages you
exchanged with Tom Thumb about the proposal, search for “Tom Thumb 2008 proposal kind:mail”. Note
that you do not need to include the “kind:” part of the search, since all kinds are included by default, but
doing so will help narrow down the results you get.
14 of 21

2. If a file bears a tag that has been excluded from the parent Tag Folder3 but has not
been excluded from the child Tag Folder, adding the file 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 file will only appear there if it matches those additional
search criteria.

The first two of these situations can be addressed by selecting the files of the child Tag
Folder and dropping them onto the icon of the parent Tag Folder.

Applying Extra Tags


Aside from the tags used in a Tag Folder’s search criteria, extra tags may also be
applied to files dropped onto a Tag Folder. This is useful if, for example, you want your
Tag Folder to show you all files with the tag “French Revolution”, but to tag files with
both “French Revolution” and “research”.

The mechanism to do this is very simple: apply tags or comments to the Tag Folder
itself.

To apply extra tags and comments to a Tag Folder, all you need to do is drag your Tag
Folder onto New Tag, enter the desired tags and/or comments in the New Tag dialog
box, and click OK. This will apply the tags to your existing Tag Folder, and also create a
second Tag Folder that searches for those tags. You may safely delete the second Tag
Folder if you don!t need it: the original Tag Folder will keep its tags even if the second
one is deleted.5

Alternatively, you can apply tags to a Tag Folder using any other OpenMeta tagging
application. You can also apply extra Spotlight comments directly to a Tag Folder by
selecting it in Finder, choosing Get Info from the File menu, and then typing the
comments into the Spotlight comments section of the Info palette.

(Note that any text entered in the Spotlight comments of a Tag Folder will be applied
without alteration6 to all files dropped onto the Tag Folder’s icon. If you set Tag Folders
to attach a prefix or suffix to your comments, make sure to include them in any
comments 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 Tag
Folders, 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 when
setting up Tag Folders, any Punakea formatted comments added to a Tag Folder’s Spotlight comments
will be parsed and processed in order to properly apply them to files. However, even in this case any
Spotlight comments that are not in Punakea format will be passed on to tagged files without alteration.
15 of 21

Note that if you have already tagged some files with a Tag Folder, and you then add
extra tags or comments to the Tag Folder, those extra tags and comments are not
automatically applied to previously tagged files. To update the previously tagged files
with the new tags, re-add them to the Tag Folder.

Optional settings
Update modification times when tagging files
Normally, when you tag a file its modification time is not changed. No data inside the file
itself has been changed in any way, so OS X does not consider the file to have been
modified. In normal use this is the desired behavior. It is not recommended that you
update modification times when tagging files unless you really, really need to.
Turning on this feature will cause backup software such as Time Machine to make
unnecessary backups of your tagged files every time a tag or comment changes on
them, and so will end up consuming lots of disk space for no good reason. This is not
necessary, because the OpenMeta framework has a transparent tag backup system
already in place so that your tags are automatically backed up and restored to your files
without having to back up the entire file 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 file synchronization applications that do not properly
support syncing extended attributes (such as tags and Spotlight comments). Some, but
not all, syncing applications may be helped by updating the modification times of tagged
files. 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 have
success syncing their tags by telling Tag Folders to update the modification time of a file
when tagging it.

To activate this feature, you will need to edit the file ~/Library/Application Support/Tag
Folders/Settings.plist. Depending on your computer, this file might open in TextEdit or in
Property List Editor when you double-click on it. In TextEdit, search for the line that says
“<key>update_modification_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 of
settings, and then change the value of “update_modification_time” from “No” to “Yes”.

Settings.plist also provides an option to update the access time of a file (using the
setting called update_access_time). It is unlikely that this option will ever be useful to
anyone, but it is there if you need it.

Note that some syncing applications do not support extended attributes (such as tags
and Spotlight comments) at all. For these apps, updating the modification time of a file
will not help in any way. This option is only useful for syncing apps that are able to sync
the extended attributes, but do not check the extended attributes when deciding
whether or not to sync the file in the first place.
16 of 21

A better way to sync your files, including the tags, is to use a syncing app that fully
supports 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 files themselves. Just make sure that ChronoSync is configured to preserve
extended attributes and to sync invisible files.
• 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 Notifications
As of version 1.1, Tag Folders can provide Growl notifications when files are tagged.
Progress reports via Growl can also be displayed when tagging a large number of files
at once. Growl notifications are configured using the Growl preference pane in System
Preferences.

Tag Prompter
Tag Prompter is a helper application that assists you in keeping the tags on your files up
to date. It watches folders for new or modified files and prompts you to tag them
automatically. This advancement makes it almost effortless to keep your files properly
tagged and organized and to avoid the otherwise inevitable accumulation of forgotten,
untagged files.

Use
Suppose you are working on a new document, and after making some good progress
you save the document to your Documents folder. With Tag Prompter watching your
Documents folder, a dialog box will appear within a moment or two offering to tag that
document by adding it to any Tag Folders you choose. Aside from selecting the
appropriate 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 Spotlight
comments 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 21

Setup
Tag Prompter can watch whatever folders you choose. To quickly add folders to the list
of folders that Tag Prompter watches, simply drag-and-drop them onto the main Tag
Folders application icon (located in your Applications folder by default). You will be
asked whether you want to start watching the folders for changes.

For more control over the list of watched folders, run the main Tag Folders application
and select “Configure Tag Prompter” from the startup dialog. This will start the Tag
Prompter configuration applet that allows you to add or remove folders from the watch
list. The “Add folders” button allows you to select new folders to watch. Use the “Edit
folder 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 for
changes, click the “Save and quit” button. You may reconfigure Tag Prompter again at
any time to change your settings.

The Tag Prompter applet is stored in the Tag Folders application support folder. Do not
move it from this location, or it will stop working.

What you will be prompted to tag, and what you will not
First, Tag Prompter will only prompt you to tag files that do not have anything written in
their Spotlight comments. If you have already tagged a file and then make changes to it,
Tag Prompter will not bother you about it.

Second, Tag Prompter only prompts you to tag files. It will not prompt you to add tags to
folders you create. If you want to tag a folder you will have to do so by the usual
methods.

If you tell Tag Prompter to watch all the subfolders of a folder and then later make a new
folder somewhere inside that folder, you will be asked whether you want to start
watching the new folder as well. For example, suppose I have a folder called Work that
contains three subfolders, Project 1, Project 2, and Project 3, and I tell Tag Prompter to
watch Work and all its subfolders. If I then create a new folder called Estimate inside
Project 1, Tag Prompter will pop up and ask me if I would like to start watching Estimate
for changes.

How it works
Tag Prompter uses OS X’s built-in technologies to provide its services. The actual
watching is done by the operating system itself using a “launch agent.” Launch agents
are 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 computer
at all.

The launch agent called com.vndv.tagfolders.tagprompter watches the folders you


choose for changes. When a change is detected by the launch agent, one of Tag
Prompter’s Applescripts is called to determine whether or not to prompt you to tag the
new/changed file(s).
18 of 21

However, when a launch agent watches a folder, it only looks down one layer deep: if a
file changes in a subfolder of the watched folder, you will not be prompted to tag it. To
watch the contents of the subfolder, you must add the subfolder to the list of watched
folders.

What not to do
Do not go crazy watching subfolders! It is a bad idea, for example, to tell Tag Prompter
to watch all the subfolders of your home folder. First, you really don’t want to be
prompted to tag every little file that ever changes in the bowels of your Library folder.
Second, although I worked hard to make Tag Prompter as quick as possible, sorting
through 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 of
your iPhoto library, etc. Applications like these already have built-in systems for
managing files (including tagging with keywords), and their data should be left alone.

I recommend watching your Documents folder, perhaps your Desktop folder, and any
other folders that you actively use on a regular basis. Leave those dusty old long-term
storage folders off the list; watching them will only slow things down for no real gain.

Comment to Tag Importer


Tag Folders 2.0 includes an importer applet that can import Spotlight comments into
OpenMeta 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 the
startup dialog of the main Tag Folders app.

You may either import the comments of all files on your computer, or the files in a folder
you choose.

You will be informed of how many files there are to be imported, and asked how often to
display progress notifications.

Finally, you will be asked for the formatting system you used on your existing Spotlight
comments. Since this may not be the same as what you told Tag Folders to use for
formatting your current comments, you have to define it again here.

The importer will then copy over all the Spotlight comments of your files into OpenMeta
tags. Progress notifications will be displayed at the frequency you specified.

When the import is complete, you will be informed if there were any files whose
comments could not be imported. If there were any such files, a list of them will be
created on your desktop in a file called Spotlight comment import error log.txt.

Finally, the importer will double check that there are no illegal characters in the
OpenMeta tags, and will clean them up if there are.
19 of 21

Troubleshooting
If your Tag Folders do not behave as expected, there are a few things you can try.

1. Make sure the file you want to tag meets the criteria of your Tag Folder. If you
cannot tag a file with a particular Tag Folder, check whether the Tag Folder has been
set to accept only certain files and whether your file meets those criteria. To add
your file, 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 file.

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 files 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 file 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 first 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 file and probably
waiting for you to give it an answer to a question. Note that in the second
example, the number in the first column will be different every time.

If nothing comes back as a result of this command, select “Configure 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 files 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 find 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 files 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 fix 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 fix.

Getting Support, Sharing Ideas, Etc.


Tag Folders is freeware, and I actually do something entirely different from software
development with most of my time. So I promise you nothing. That said, I like being
helpful, and there are lots of other people in the world who like being helpful too. If you
want to talk about Tag Folders, report a bug, get some help, or share an idea, the best
way 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 users
Tag 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 like
to help translate the Tag Folders interface into your language, please contact me by
posting on the Tag Folders Google Group.

In earlier versions of Tag Folders, non-English users sometimes received errors due to
English specific terms, and had to modify the Tag Folders source code. This should no
longer be the case.

Source code, Licencing, and Modifications


Tag Folders.app, Tag Prompter.app, and Comment to Tags Importer.app are distributed
under the GPL 3.0 licence. A copy of the licence is included inside the application
bundle of every Tag Folder, and inside the application bundle of Tag Prompter.app and
Comment to Tags Importer.app. The source code for Tag Folders can be accessed by
opening Contents/Resources/Scripts/main.scpt inside the application bundle of any Tag
Folder. The source code for Tag Prompter can be accessed by opening the .scpt files in
Contents/Resources/Scripts/ inside the application bundle of Tag Prompter. The source
code 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 you
make any improvements to the source code of Tag Folders or Tag Prompter and believe
21 of 21

they may be beneficial to others, please consider submitting them to the Tag Folders
project by posting on the Tag Folders Google Group. The Tag Folders icon is based on
an icon created by Jonathan Hunt at iconaholic.com, and is used by permission, with
many thanks.

You might also like