Command spotlight

You know it’s there—why can’t Spotlight find it? The Tiger feature that promises to be your own personal Google does have its limitations, especially when searching your Mac’s most out-of-the-way corners. For greater control over the way Spotlight works, take a trip to Terminal. Its new mdfind, mdls, mdimport, and mdutil commands help you find files, control exactly what Spotlight indexes, and search by metadata.

Find Files from Terminal

Like a regular Spotlight search, the

mdfind

command lets you quickly find files on your Mac according to keywords—and it adds an extra twist or two. For example, if you run the command

mdfind Walden

, you’ll find any files that contain the word Walden in their names, content, or other metadata.

Get Specific If you know that a file is in a certain directory, or you want to search only files in that directory, use the

	-onlyin	directory name	

option to narrow down the search—for example,

mdfind walden -onlyin /Users/thoreau/Documents

.

Tip: Drag the folder you want to search to the command-line prompt to add its path name quickly.

Try Live Searches Another option lets you run a live search, which updates results as users add files. This is particularly useful if you’re waiting for people to put files in your Drop Box, or if you run a server and want to see when files containing certain content or metadata appear in a shared folder. Since Spotlight is constantly indexing your files, you can see when it adds new files that match certain criteria.

For example, if I type

mdfind -live Walden

, the command will alert me each time it discovers an additional matching file. A message will appear at the bottom of the Terminal window—for instance,

Query update: 20 matches

. The command will continue to update this number until I stop it by pressing control-C. If you want to see the names of all the files, then you must run the command again.

Have We Met? If

mdfind

’s abilities sound familiar to you, then you’re probably acquainted with the

locate

command. However, there are some differences between the two. The

locate

command searches all the nooks and crannies of your Mac but looks just for file names. Also, it updates only when you run the weekly Unix maintenance routine or use the command

/usr/libexec/locate.updatedb

.

On the other hand,

mdfind

updates its results automatically every time you create or add a new file, but it doesn’t search everywhere on your Mac. You can combine the powers of

mdfind

and

locate

using another of Spotlight’s command-line additions—the

mdimport

command.

Force Spotlight to Index Files

By default, Spotlight ignores many directories, such as your Classic System Folder. Sure, that makes results easier to comb through if you never need to look for OS 9 fonts; but if you do need to search these directories, it can be a real pain.

Use the

mdimport

command to add files to your Spotlight indexes. When you do, you’ll be able to search for much more than the default selection of files and folders. (When you add to your indexes this way, Spotlight won’t continue to index the new files automatically. You’ll have to run the command again.)

The

mdimport

command forces Spotlight to index a folder. When you run the command, you’ll index all the contents of the directory and its subdirectories. The basic command structure looks like this:

mdimport -f

directory name .

So if you want to index your Classic System Folder, you’d type

mdimport -f /"System Folder"

(assuming that the System Folder is at the root level of your startup volume).

If you want to index other folders, or if Spotlight is not finding certain files, use the same command with the appropriate paths to index or reindex specific directories or volumes. Note: Spotlight doesn’t index text files that lack the .txt extension. That means you won’t be able to improve its ability to find, for example, configuration ( .config) files and preference ( .plist) files.

Stop Spotlight Indexing

If you peruse the Spotlight preference pane, you’ll see that you can prevent Spotlight from indexing certain volumes or folders. Click on the Privacy tab and add the areas you don’t want indexed to the list. That’s handy if you don’t want your Mac grinding away every time you connect your backup drive to archive files, or if you don’t want it to provide duplicate search results (the same files on both your main drive and your backup) when the backup is connected.

The

mdutil

command gives Mac administrators similar powers. (You must preface it with

sudo

, which tells Terminal to run it as the superuser after you authenticate with your administrator password.) Using this command, you can specify which volumes to index and you can also make Spotlight reindex volumes by erasing the current indexes.

The On-Off Switch To turn indexing on or off for a volume, run

sudo mdutil -i on

volume name or

sudo mdutil -i off

volume name , respectively. For example, if you want to turn off indexing for a volume called Backup, the command would be

sudo mdutil -i off /Volumes/Backup

.

To delete the index for a volume, run the command

sudo mdutil -E

volume name . If indexing is on for the volume, Spotlight will reindex it immediately. If indexing is off, it will remain so (until you turn it on again). That means you’ll reclaim the disk space that the index used.

Meet Your Metadata

Spotlight doesn’t just index file names and file content. It also indexes metadata , which is data about data. Metadata might include the last save date or author of a Microsoft Word document; the artists, composers, albums, and genres of digital music files; or, in the case of an e-mailed file, the sender’s e-mail address. Every file contains an astonishing list of metadata.

The problem is that you probably don’t know what kinds of metadata you’ve got in your index. The

mdls

command can help. It lets you see what type of metadata Spotlight has indexed for any file. Running the command, in the format

mdls

file name.txt , shows the metadata for a text file (See screenshot). You can see some simple information, such as the following:

kMDItemKind = “Plain text document”

kMDItemLastUsedDate = 2004-07-02 18:19:07 +0200

The first line shows the document type, and the second line is the last date someone changed the file. You’ll see different metadata for different files. A file you downloaded from a Web site will have a URL. Music files will have tag information. A digital photo will have everything from the camera’s make to whether your flash was on. Once you know the odd terms ( kMDItemKind isn’t exactly colloquial), you can search for any of these metadata types.

Say you want to find a file that a friend sent you by e-mail, but you can’t remember its name or what it contained. This is a piece of cake: search for the sender’s e-mail address. Run the

mdls

command on an e-mail message to find out how to search for such metadata. (You can just drag a file to the prompt to enter its path and name.) The attributes it returns are the arguments you can use.

Once you’ve got the right arguments, you’re ready to search. For example, to find a file received via Apple’s Mail (Spotlight doesn’t index Entourage databases or e-mail from some other programs), you’d use the

mdfind

command like this:

mdfind "kMDItemAuthorEmailAddresses == '*macworld.com*'"

This command searches for any file received from a macworld.com e-mail address. Pay close attention to the use of quotation marks, asterisks, capital letters, and the double equal sign (

==

). Type

man mdfind

for more on this command’s syntax.

All the Attributes If you’d like to see all the attributes you can search by, use the

mdimport

command. Type

mdimport -A

in Terminal, and you’ll see a long list of more than 100 attributes, as well as a short description of each one.

Needling the Haystacks

With Tiger’s Spotlight commands at your disposal, you now have totally new ways to search for the most obscure files on your Mac. Best of all, you can combine these commands with the many other Terminal commands you already know.

[ Kirk McElhearn is a coauthor of Mastering Mac OS X, Tiger Edition (Sybex, 2005). His blog features articles about Mac OS X, the iPod, iTunes, and much more. ]

Spotlight indexes an incredible array of metadata for each of your files. Use the mdls command to find out what metadata a file type (in this case, a text document) includes. Once you know these attributes, you can perform detailed searches.