Usage
If you want to learn about ack or you’d like to understand how to set up your .ackrc file then take a look at the Home page.
AckMate’s menu item is installed under Edit->Find->Search Project With AckMate... and its default keyboard shortcut is ctrl-option-command-f.
If you want to change AckMate’s keyboard shortcut to something else, you can easily do so in System Preferences under Keyboard->Keyboard Shortcuts and add a new shortcut for TextMate called Search Project With AckMate... like this:
Most of the time, you’ll just type in your search term and hit “Return” or “Command-Return” (which limits your search to the folder you have selected in TextMate’s project drawer).
By default, AckMate treats your search term as a regular expression. If you want to switch that off, you check the Literal match checkbox.
The only other non-obvious checkbox is Use TextMate folder references.
Under TextMate’s advanced preferences pane there’s a “Folder Pattern” setting in the “Folder References” tab. This setting controls which folders TextMate should exclude from your project view.
ack also has a list of folders (such as .git) which it, by default, excludes from searching.
Use TextMate folder references will cause AckMate to use both ack’s ignored-folders list and TextMate’s “Folder Pattern” when deciding if a folder should be ignored.
The Options field accepts a space-separated list of options you’d like to pass to ack.
Most of the time you’ll be passing filetype options like ruby or noyaml. AckMate will autocomplete your filetypes from the list of filetypes that ack knows about.
If your option starts with a - (dash) character then AckMate won’t autocomplete and it will simply pass your option on to ack as-is.
Probably the only dash-prefixed option you’ll be using is -G which is a way of specifying a regular expression that the fully-qualified filename must pass in order to be considered ‘interesting’.
For example: -Gmodels will only search files with a fully-qualified name containing ‘models’. Do not put a space between the -G and the rest of the option.
It’s also possible to amend the list of filetypes in the options field but you’ll need to tell AckMate to reload the filetypes before you can use it as a filetype.
You do this either by selecting the “Edit->Find->Search Project With AckMate” menu or by pressing Ctrl-Opt-Cmd-F (or whatever system-preferences keyboard shortcut you’ve chosen).
At least three people have asked how to restrict the search only to a given subfolder. Holding (or releasing) the Command key toggles the AckMate window between “search the whole project” and “search in selection” mode.
When the Command key is pressed, you can see the “Search” button change to “In Selection”. (If you don’t have a folder selected in TextMate, the search button is disabled during “In Selection”.)
So basically, in the AckMate window: Return searches the whole project, Cmd+Return searches just your selected folder.
TextMate’s “Find in Project” window is actually shared across all of your open projects. This may be good or bad, depending on your point of view. For me it’s bad.
AckMate is different in that each of your projects gets its own AckMate window.
This means that each project’s AckMate window can remember its own search settings and you won’t clobber your project’s search results by searching in another project.
Assuming ~/bin is in your search path, create a symbolic link from the command line like this:
ln -s ~/Library/Application\ Support/TextMate/PlugIns/AckMate.tmplugin/Contents/Resources/ackmate_ack ~/bin/ack