Table of Contents

What is GoToFile

GoToFile is a flexible, and accurate utility to find and manage files and folders on your Mac as fast as you can type.

Initial Setup

GoToFile works out-of-the-box without any configuration, but we recommend setting up a keyboard shortcut to open the search panel. To do this, select “Settings…” from the menu item and configure the System Wide Hot Key in the Access section of the Settings dialog.

Basic Operation

GoToFile runs in the background and only becomes visible when you need it. Select “Go to File…” from the menu item or press the configured keyboard shortcut to open the search panel. You will see an input field like this:

You can start typing right away. GoToFile will recursively fuzzy-search for filenames in your home folder containing the characters you type in the order you type them. You can use the cursor keys ↑ and ↓ to navigate the result set. Press ⏎ to open the selection with its default application. Press ⇧⏎ to open the selected item in the frontmost application.

The icon of an item in the result list can be dragged on applications supporting drag&drop. The search panel will be automatically be hidden when a drag operation is initiated. If the operation fails (no valid drop target has been found) the search panel appears again.

GoToFile features a configurable context menu which is opened by right-clicking in the result list.

When showing files, the status bar shows numbers in square brackets like this: [number/number] or [number/number/number]. The first number represents the number of selected items. The second one the number of displayed matches. The third number is only displayed in Search Mode. It represents the number of total matches.

Fuzzy Search

When entering a lower case search string GoToFile will search for filenames which contain all the characters of the search string in the order they appear in the search string. Matching characters may be interspersed with others. The lower the distance between matching characters, the higher the item will be ranked. Upper case characters in the search string will favor matching characters at the beginning of words or upper case characters within words (CamelCase).

You can use more than one search term by separating them with at least one ␣ (space) character. The order of search terms is not important. If you want to search for items containing a ␣ character you have to prefix it with a backslash: lng\ fn will match long filename but not longfilename.

Regular Expressions

If fuzzy searching does not yield the desired result you can use regular expressions. Search terms prefixed with + or - will be considered a Regular Expressions. The positive Regular Expression (+) will show only matching items while the negative one (-) will hide matching items.

Regular expressions can be used by themselves or mixed with ordinary search strings. They have to be separated from other search terms by at least one ␣ (space) character.

The regular expression syntax currently supported by GoToFile is that specified by ICU. It is described in detail at http://userguide.icu-project.org/strings/regexp. The site https://regex101.com is a great place to experiment with regular expressions.

Regular expression matches in GoToFile are case insensitive.

In the search field invalid Regular Expressions are displayed in red. They are ignored and don’t affect the search.

Metadata

GoToFile allows for searching by an item’s metadata. Searchable properties include file size, owner, and timestamps. For a complete list see the tables below.

metadata search is disabled by default. You can enable it in the Search tab of the GoToFile Settings. Note that this feature increases memory usage and scan time by a few percent. Decide for yourself if this feature is worth the trade-off.

A metadata query begins with the backslash (\) character. If the next character is an exclamation mark (!), the query is negated. Following this, you specify the key for the attribute you want to query. An operator (○) may precede the numeric value, which itself can be optional depending on the specific key.

When entering a metadata query GoToFile may color parts of it. Orange parts are not yet complete while red parts inticate an error.

Timestamp Related Attribute Keys

GoToFile handles four different timestamps:

Query by Age

The keys (tb, tc, tm, ta, or t*) are followed by an operator (○), a numeric value, and a unit key.

Query by Date Component

The keys (tb, tc, tm, ta, or t*) are further specialized using one of the keys below. These are followed by an optional operator (○) and a numeric value. If no operator is specified, = is assumed.

Query by Date

The keys (tb, tc, tm, ta, or t*) are followed by an optional operator (○) and a value. If no operator is specified, = is assumed.

Other Attribute Keys

Attribute Keys for Sorting Only

These keys cannot be queried. They can only be used to enforce a sort order.

Operators

Note: To emulate a NOT operator use a negative query: \!usoma-zone to match items not owned by user soma-zone.

If no operator is specified, = is assumed.

Enforcing Sort Order

By default GoToFile will present the results ordered by an internal ranking. You can, however, also sort by metadata. This can be done by either appending the order specification to the end of the metadata query or by specifying the search order immediately behind the metadata key.

See sections Timestamp Related Attribute Keys, Other Attribute Keys, and Attribute Keys for Sorting Only for a list and description of all valid keys.

Operating on the Selection

Once the desired item has been found and selected GoToFile allows for several operations. These operations are accessible via context menu, keyboard shortcuts or Action Mode (⌘K).

For a complete list of all built-in actions consult the section keyboard shortcuts.

In addition GoToFile allows for user defined actions. See section Actions for details.

File Management

GoToFile supports basic file management functionality. It allows you to rename, copy, move, and trash items.

Rename

Select the item you want to rename and press ⌃⏎. Change the name and press ⏎.

Copy

Press ⌃C to mark the selected items as the copy source. A small badge will appear below the icons of the selected items. Next select your copy destination and press ⌃V. A confirmation dialog is presented. Once the copy operation is confirmed, the copy source list is cleared.

You can extend the copy source list by selecting other items and pressing ⌃⇧C. Pressing this key combination on an item which is already part of the copy source list whill remove it from the list.

Should you want to verify which items are currently in the copy source list, press ⌘M in order to switch to Marked Items Mode and press ⌘M again. You can remove items from this list by selecting them and pressing ⌃⇧C.

Move

Press ⌃X to mark the selected items as the move source. A small badge will appear below the icons of the selected items. Next select your move destination and press ⌃V. A confirmation dialog is presented. Once the move operation is confirmed, the move source list is cleared.

You can extend the move source list by selecting other items and pressing ⌃⇧X. Pressing this key combination on an item which is already part of the move source list whill remove it from the list.

Should you want to verify which items are currently in the move source list, press ⌘M in order to switch to Marked Items Mode and press ⌘M again. You can remove items from this list by selecting them and pressing ⌃⇧X.

New Folder

To create a new folder press ⌃⇧N. A dialog will appear where you enter the name of the new folder. Click the Create button (⏎) to create the folder.

Should you, at the time you create a new folder, have marked items for either copying or moving, the dialog will contain an additional button “Create with Copy/Move Sources”. Click this button (⌥⏎) in order to create the folder and copy/move the copy/move sources into the new folder.

The Create button becomes inactive when the folder name is empty or if an item with the same name already exists in that location.

Where the new folder is created depends on the selection. When a folder is selected, the new folder is created inside the selected folder. When a file is selected, the new folder is created in its parent folder. In Browser Mode the same rules are followed. In addition, should no item be selected, the new folder will be created in the browser’s current folder.

Trash

Press ⌘⌫ to move the selected items to the Trash.

Drag&Drop

GoToFile as a Drag Source

The icon of an item in the result list can be dragged on applications supporting drag&drop. The search panel will automatically be hidden when a drag operation is initiated. If the operation fails (no valid drop target has been found) the search panel appears again. You can configure to bring back the search window after a successful drag&drop operation in the Settings.

If the icon of an selected item is dragged, all selected items take part in the drag operation. Dragging the icon of an unselected item will only make this particular item a drag source. Selected items will be ignored in this case.

GoToFile as a Drag Destination

When the preferences option “Hide search field on de-focus” is enabled in GoToFile’s Settings, the result list of GoToFile may be used as a dragging destination for other applications. This preferences option can also be changed with a button which is revealed when moving the mouse cursor over the top-right corner of the search field.

Dropping works in all Major Modes. Modifiers work the same way as in Finder to enable copying (⌥), moving (⌘), or creation of aliases (⌥⌘).

In Browser Mode

Browser Mode is the only mode representing the contents of a single folder, its Current Folder. Dragging an item from another application onto a folder in the result list will make this folder the dragging destination. Dragging an item above or below a row in the result list will make the Current Folder of this mode the dragging destination. A row representing a file cannot become a dragging destination.

In Search, Recent Items, and Marked Items

These modes support path component selection. If a path component of a row has been selected, this selection is honored for Drag&Drop as well! Although the row might initially have represented a file it will be considered to be the folder selected in the row’s path component selection.

Dropping an item onto a file without active path component selection will make the folder containing the file the dragging destination.

Major Modes

Search Mode (⌘S)

Queries entered in this mode search all directories that make up the current Project recursively. These directories are scanned when GoToFile starts. While GoToFile is running it keeps track of all changes to the project’s search directories an updates its cache in the backgeound.

By default the number of results in this view is limited to 100. This value can be changed in the GoToFile Settings. You can temporarily disable this limit using the built-in action “Ignore Maximum Result Set Size” (⌘S).

The info bar shows the number of selected items, the number of matches in the result list, and the total number of matches. In case not all configured search folders are accessible, the number of total matches is followed by an asterisk.

Search Scope

Search by Filename or by Complete Path

To the right of the Info Bar you see an icon that, depending on the search mode, looks like a % or like a % with the left circle omitted. Click it to switch between filename-only and full-path search. Its keyboard shortcut is ⌘⇧O.

Showing Files or Folders Only

To the right of the Info Bar you see two small icons, one depicting a file, one depicting a folder. Clicking on them lets you show or hide items of the respective type. Alternatively you can press ⌘⇧F to toggle displaying of files and ⌘⇧D to toggle displaying of directories.

Filter by Path

The modes Search Mode, Recent Items Mode and Marked Items Mode allow for filtering by path.

Use ⌃, (Shrink path selection) or ⌃. (Extend path selection) to highlight a path component of the currently selected item. Press ⌘- (Ignore selected folder) to temporarily hide all items located at the highlighted path component or one of its descending folders. Press ⌘= (Focus on selected folder) to temporarily show only items located at the highlighted path component or one of its descending folders. The filter icon will be displayed in the Info Bar and the result set will be immediately updated.

The commands ⌘- and ⌘= also work without highlighting a path component. In this case the selected folder or, in case the selected item is a file, the folder containing the selected file is used.

Both actions can be combined and performed multiple times to narrow down the result set. Click the filter icon or press ⌥⎋ (Clear filter) to reset the filter.

Limit Search Scope to the Currently Selected Item

Press ⌘⇧S to recursively search the selected folder. If the selected item is a file the folder containing the file will be searched recursively. This action will create an ad-hoc project. Use the Project Selector (⌘P) to switch back to a configured project or press ⌘P two times to switch back to the most recent project.

The result is similar (not identical!) to focussing on path components (⌘=). Global rules apply to ad-hoc projects as well but only real projects can have directory-specific rules.

Search Folder Containing the Document of the Frontmost Application

This action creates an ad-hoc project from the folder containing the document of the frontmost application.

1. Open the search panel while any document-based application is active
2. Press ⌘⌥S

App Filter: Filter by files supported by the Frontmost Application

This functionality is ideal when using GoToFile as a replacement for macOS’ Open… dialog. It will pre-filter the index to include only items which are relevant to the frontmost application. This filtering happens whithout any delay.

1. Open an applications, Numbers for this example
2. Bring up GoToFile
3. Press ⌘\ to enable frontmost-application filtering; The icon of the frontmost application appears at the right of the search field
4. Enter a seach string

GoToFile will now only show Numbers documents.

But Numbers can open other file formats as well. If you want so see those too, you have to relax the filter by pressing ⌘\ again. The icon to the right of the search field will turn grey and GoToFile will show every file Numbers can open.

Press ⌘\ again to disable the App Filter.

The Project Editor

You use the Project Editor to make changes to the current project, define new ones, or delete existing projects.

Create a New project

1. Press ⌘⌥P to open the project editor
2. Create a new project by clicking the + button below the Projects list
3. Name your new project
4. Add the desired folders to the “Search Folders” list below the Projects list
   1. (optional) Specify if and how you want to limit the search depth for the Search Folder. By default the search depth is unlimited.
   2. (optional) Specify whether you want the Search Folder itself to appear in the search index. By default only the contents of the Search Folder is added.
   3. (optional) Specify subfolders to exclude from the Search Folder just created. By default no subfolders are excluded.
   4. (optional) Specify if GoToFile should honor the global list of excluded folders (as configured in the GoToFile Settings) for this Search Folder. By default GoToFile takes the global list of excluded folders into consideration.
   5. (optional) Specify rules to configure which items inside the Search Folder should appear in the index. By default any item in the project folder will appear in the index.
   6. (optional) Specify if GoToFile should honor the global rules (as configured in the GoToFile Settings) for this Search Folder. By default global rules will be considered.

Scan Parameters

Patterns

To keep a folder from being scanned, or to specify which items to include in GoToFiles index you have to specify a pattern describing the file or folder.

Literals, Wildcard patterns (aka Glob patterns), and regular expressions may begin with, and/or contain a path separator. In the former case the pattern is matched against the complete path, relative to the root directory being scanned. In the latter case the pattern is matched against the tail of the complete path. Patterns without path separator are matched against the item name only.

We assume that a directory Folder with the following contents has been configured for searching:

Folder
├── Archive
│   ├── Private
│   │   ├── John
│   │   ├── Mary
│   │   └── Tim
│   └── Work
│       ├── John
│       ├── Mary
│       └── Tim
└── Live
    ├── Private
    │   ├── John
    │   ├── Mary
    │   └── Tim
    └── Work
        ├── John
        ├── Mary
        └── Tim

The patterns will be matched against different sections of a path according to the existence and position of path separators in the pattern:

All matches are case insensitive.

GoToFile understands three types of patterns: Literal, Wildcard (Glob), and Regular Expression.

Literal

This is the most basic pattern. There are no special characters.

Wildcards (Glob)

Use this type of pattern for basic matches. GoToFile supports the following wildcards:

Regular Expressions

In case Wildcards are not sufficient to describe a path you can use regular expressions. The regular expression syntax currently supported by GoToFile is that specified by ICU. The site https://regex101.com is a great place to experiment with regular expressions.

Regular expression matches in GoToFile are case insensitive.

Subfolders not to Scan

The default project that is defined in GoToFile is called Home. It contains the home folder as a directory to search. But the home folder contains subfolders which don’t contain items users are likely to look for. One such folder is Library. The default project Home has an exception configured which tells GoToFile to not scan the folder Library. This saves time when traversing the home directory and it keeps the result list from being cluttered by unwanted items.

What if there is a folder Important in Library you’d like to scan? The list of folders to search is processed from the most specific to the most generic. You just have to create a new Search Folder ~/Library/Important. GoToFile will move it before the already configured home folder. When processing this list is reversed. For this reason the default project Home includes the folder ~/Library/Mobile Documents/com~apple~CloudDocs after the home folder. It contains your iCloud documents which would otherwise not be searched.

For every Search Folder you can choose to ignore the global folder exclusion list.

Hint: You can add a folder to this list while searching. Select a folder in the search result list and click ‘Exclude from Search Folder’ from the popup menu in the search field.

Items to Ignore

By default every item found in a configured folder is recorded in an index. But for every folder in a project rules can be configured. These rules tell GoToFile which items should be included in or excluded from the index.

GoToFile knows two types of rules: include and exclude. When defining include rules only items matching the rules will be recorded in the index. Everything else is ignored. When defining exclude rules items matching the rules will not be recorded in the index. Everything else is included.

For every Search Folder you can choose to ignore the global item ignore list.

Duplicating Scan Options

Defining excluded subfolders and folder rules is done on a per-folder basis. If a project consists of multiple folders these settings don’t have to be made to every folder manually. Just drag an already configured folder from the ‘Search folders’ list and drop it on another folder in this list. All settings of the drag source will be applied to the drag destination.

Search Parameters

These options don’t affect the index. They just control which items from the index are displayed. Changes to these settings are always persisted.

Filter by Item Type

Here you select if you want to see files and/or folders in the result list. You can toggle this option from the search field by pressing ⌘⇧F (toggle files) and ⌘⇧D (toggle directories).

Search Path or Filename Only

When checked the whole path is searched instead of the filename only. This option may slow down the search a bit. You can toggle this option from the search field by pressing ⌘⇧O (with ‘O’ as in ‘Only’).

Browser Mode (⌘B)

Use this mode to traverse a file system hierarchy manually. It works very much like Finder’s List View.

If you know the name of an item Search Mode is the fastest way to get there. If you don’t, you press ⌘B to activate Browser Mode. Initially the contents of you home folder will be displayed. Type a few characters to only display matching items. Press ⌘↑ to go to the parent directory, press ⌘↓ to browse a folder. ⌘⇧S will search the selected folder (or the folder containing the selected file) recursively.

Hidden Files

Just like Finder the Browser Mode does not show files or folders with names beginning with a dot. Press ⌘. to show these items. Press it again to hide them again.

Cycle Base Directories

Another useful command is ⌘/ (Cycle base directories). Use it to switch to your home directory, the filesystem root (/), and the /Volumes folder.

Browse Sibling Folder

Consider this folder structure:

Folder
└── Archive
    └── Private
        ├── John *
        ├── Mary
        └── Tim *

Browse next/previous sibling folder: If you are browsing folder John and you want to quickly browse folder Mary, press ⌃.. Press ⌃, to go back to John. The selection and search string will be remembered, so when you come back to John, the Browser will look exactly the way it did before you browsed its sibling folder.

Browse next/previous marked sibling folder: In the folder structure above, John and Tim have been marked. You can press ⌃⇧, and ⌃⇧. to skip over Mary when browsing sibling folders.

Recent Items Mode (⌘R)

This mode shows a searchable list of the most recently created/modified items in the directories associated with the current project. You can exclude folders from monitoring by unchecking the ‘Show in Recent Items’ checkbox of the folder in the Project Editor.

When GoToFile starts this list is empty. It is populated in real time while GoToFile is running.

If no search term is entered the list is ordered by modification date in descending order. Once a search term is entered the list is ordered according to best matches.

By default the number of recent items remembered is limited to 100. This value can be changed in the GoToFile Settings.

The search scope section of Search Mode applies to Recent Items as well.

Marked Items Mode (⌘M)

This mode shows a searchable list of files and folders marked in any of the other modes using the ⌃M keyboard shortcut. Use ⌃M on an already marked item to remove it from the list.

You can recognize a marked item by its star badge in the upper left corner of the item’s icon.

There is one list of marked items for all Projects. It is persisted across restarts.

The search scope section of Search Mode applies to Marked Items as well.

Minor Modes

Projects Mode (⌘P)

This mode provides a searchable list of Projects. Use this mode to switch to another Project.

Projects give you a way to search otherwise unrelated folders at the same time. You can define default settings on a per-project basis.

Switching projects

1. Press ⌘P to get to the list of projects
2. Type a few characters or use the cursor keys to make the new project the selected item
3. Press ⏎ to select the project and switch back to Search Mode

History Mode (⌘H)

This mode provides a searchable list of previously entered queries. Select a query and press ⏎ to return to the Major Mode History Mode was called from and make the selected query the current query.

Actions Mode (⌘K)

Once one or more items are selected in one of the Major Modes you can bring up the Actions Mode. It provides a searchable list of actions that can be performed on the selection.

Action Mode always displays all user defined actions. Depending on the settings in the Appearance tab of the GoToFile Settings it also shows all applications the selection can be opened with and all applicable internal actions.

For a complete list of the available actions please check out the Keyboard Shortcuts tab of the GoToFile Settings.

Settings

Open the GoToFile Settings dialog by pressing ⌘, while the search window is open, by selecting Settings… from the menu item, or by selecting Settings… from GoToFile’s application popup menu which is opened when you click on the colored square field to the left of the search field.

The Settings window is divided into five sections: Access, Search, Appearance, Hotkeys, and Updates / License.

Access

Here you can set the global hotkey to bring up the search panel. The Menu Item can also be hidden if desired.

If you want to launch GoToFile at login, check the corresponding checkbox. If the checkbox is disabled please open the System Preferences, select Users & Groups, select your user account and then Login Items. Drag the GoToFile application icon onto this list.

Behavior

When Warn before movin item to Trash is enabled, GoToFile asks your confirmation before performing the operation.

By default the GoToFile search window will be hidden as soon as you activate another application. When unchecking Hide search field on de-focus you can make the search window sticky. This may be useful for using GoToFile’s selection as a drag&drop destination.

When GoToFile is used as a drag&drop source the search window is hidden as long as the drag operation lasts. When the operation end successful the search window appears again. If you’d like the search window to remain hidden, select Hide search field after successful drag&drop operation.

With Maximum number of results in Search Mode you limit the maximal number of items visible in the result table of Search Mode.

With Maximum number of results in Recent Items Mode you limit the maximal number of items visible in the result table of Recent Items Mode.

The option Process Metadata allows you to switch metadata processing on or off. Switch it off if you don’t want to use it or if you want to shave off a few percent of GoToFile’s memory usage and scanning speed. The search speed is not affected by metadata processing. See Metadata for details.

You can also configure if you want GoToFile to Treat Bundles as Files. This setting affects the filtering of results by type.

Indexing

Don’t scan folders matching pattern: This is where you can exclude folders from being scanned. Configuration works similar to exclusion lists in the Project Editor. Exclusions defined here are appended to the list of excluded folders of all search folders of any project unless the scan folder’s ‘Ignore global exclusions’ box is ticked. Patterns are matched against paths relative to the search folder. So if you configure /tmp and the current search folder is /Users/me the pattern will match /Users/me/tmp. Global exclusions also affect ad-hoc projects.

Don’t show items matching pattern: You can prevent certain items from appearing in the index. The default settings will match temporary (filenames ending or beginning with ~) and hidden files (filenames beginning with .). Refer to the Project Editor for details.

Appearance

Use Font Weight to configure the font weight to be used for GoToFile’s search results and search string.

In Actions visible in Actions Mode you can configure which actions you want to see when switching to Actions Mode. User defined actions will always be visible there. If you want you can add all Open With… actions. Another option is to include all internal actions (Info, Copy, Copy Path, Type Path, …). This might be useful if you don’t want to remember all the different keyboard shortcuts.

Below, with Show Metadata in Result List, you can decide if/when you want GoToFile to display metadata in the result table.

In order to save vertical, space not every metadata item is displayed on a separate row. Instead there are two groups. To save horizontal space, GoToFile uses symbols instead of labels.

Actions

GoToFile may be extended with Actions to perform user-defined tasks on the selection. These Actions are accessible by bringing up Actions Mode (⌘K). You may also assign specific keyboard shortcuts in the Hotkeys section of the GoToFile Settings to perform them directly.

The panel consists of two major sections: The action list to the left and the configuration tab view to the right. The configuration tab view consists of three tabs: General, Availability, Output.

Adding an Action

1. Click the + button below the action list. A new action is created.
2. Decide whether the action performs an external application/executable or a script that you embed in GoToFile. Choose the latter if the script is just a few lines short and used only by GoToFile. Choose the action kind from the popup button accordingly.

Adding an External Application/Executable

1. Click on the Set… button
2. A file dialog is shown. Select the application bundle or executable you’d like to run for this action
3. GoToFile will change the action name according to your selection. If needed click on the new action name in the action list to customize it.

If your action consist of an application bundle this is all there is to be configured. The command will open all selected items with the specified application.

If you chose a script or other executable you have several more configuration options. You can configure the working directory and command line arguments. You can also process an action’s output and open it in an application, a Terminal or GoToFile.

Adding an Embedded Script

Enter the script in the text view. Make sure to provide a shebang line to specify the interpreter you’d like the script to run on like so:

#!/bin/sh

GoToFile will run this script with the environment variables that would be set for a regular login session using your login shell.

Configuring an Action

General

The controls available in this tab depend on whether the action is supposed to open the selection with an application, process the selection with an external script or process the selection with an embedded script. This is what the Action Kind popup button is for.

Application / Executable

Click on the Set… button to select an application you’d like to open the selected items with or an executable to process the selected items with.

Command line arguments are specified in the table below. Each command line argument has to be entered on a new line. GoToFile will replace some placeholders with their actual values. These placeholders are:

Example: Eject selected Volume

The most elegant way is probably to let Finder do the work and error reporting. An AppleScript one-liner will do:
shell /usr/bin/osascript -e 'tell application "Finder" to eject disk "DISK"'
Here is how this is accomplished via a GoToFile Action:

1. Set /usr/bin/osascript as executable
   By default the directory /usr is hidden in the system macOS file selector dialog. You can jump to it directly by pressing ⌘⇧G and entering /usr/bin into the panel. Then select osascript..
2. Add two command line options:

• -e
• tell application "Finder" to eject disk "${BASENAME}"

In the availability tab add public.volume to the list. This ensures that the action will only be available when a mount point is selected.

And this is what the configuration looks like:

Embedded Script

Your script is entered directly into the text field. GoToFile will make sure you specify the interpreter in the first line, but it won’t check the script itself.

#!/bin/zsh
/usr/bin/xattr -rc "$@"

You can enter scripts in any language you have an interpreter for. Here AppleScript is used to replicate GoToFile’s built-in “Reveal in Finder” action:

Both (Application Bundle and Executable)

The working directory is the location where the executable is executed. Any relative paths will be relative to this directory. It defaults to the folder /tmp.

The last control in this tab lets you choose whether you want this action to perform a Separate run for each selected item or Run once for all selected items. This setting is only relevant for executables. Applications are started once for all selected items.

#!/bin/zsh
/usr/bin/xattr -rc "$@"

/usr/bin/xattr -rc /path/to/a
/usr/bin/xattr -rc /path/to/b

#!/bin/zsh
/usr/bin/xattr -rc "$@"

/usr/bin/xattr -rc /path/to/a /path/to/b

Availability

Most actions only make sense when applied to certain file types. In the Availability tab you can configure for which files you want the action to be available. You can provide a list of filename extensions or Uniform Type Identifiers (UTIs) for which the action is allowed. Use the + and - buttons below the table to add or remove rows. Use the button to add a UTI by selecting an example item.

Output

The output written by executables to standard output may be further processed. In this section you configure if or how this output is handled.

In case the executable is writing its output to standard error instead of standard output, check the box “Output is written to Standard Error”.

Removing an Action

1. Select the action you want to remove in the action list.
2. Click the - button below the action list.

Hotkeys

In this section you can customize most of the keyboard shortcuts used by GoToFile. Use the filter field to quickly lookup a hotkey based on its description. For a complete list of the available hotkeys please check out the section Keyboard Shortcuts in this help file.

Any hotkey can be added to GoToFile’s context menu by checking the check box between the description and the hotkey column.

A hotkey may be drawn in red. This indicates that this hotkey is already taken by macOS. Move the mouse cursor over the hotkey input field to bring up a tooltip pointing out which macOS function is using the hotkey.

Applications

Set your default file manager, terminal emulator and text editor here.

The file manager setting is honored when pressing ⏎ on a folder, when executing the “Reveal in File Manager” action, and, if the file manager supports it, the “Show Info in File Manager” action. In case the configured File Manager does not provide an “Info” service, Finder is used instead.

File Kinds

File Kinds allow you to group related filename extensions. You can query by File Kinds.

Each file kind has a unique name and a shortcut. Both have to be unique for sibling file kinds, i.e. no two siblings can share the same name and no two siblings can share the same shortcut.

You can arrange file kinds in a hierarchy. Each file kind can have an own list of extensions and subkinds. This allows you to query for ever more specific file kinds.

Consider this hierarchy. The character in braces is the shortcut, the values in square brackets

Image (i)
├── Pixel (p) [webp, avif, jp2]
│   ├── Lossy (y) [jpg, heic]
│   └── Lossless (l) [png, bmp, tiff]
└── Vector (v) [svg, eps, fig]

A query for file kind Image (\ki) finds items matched by Image and its descendents. If you’re interested in pixel images only, you append the shortcut for Pixel: \kip. GoToFile will help you build the query by suggesting the next possible shortcuts.

Note that Pixel has both, extensions and subkinds, defined. This was done because webp, avif and jp2 may use lossy or lossless compression. The same could be achieved by adding them explicitly to Lossy and Lossless.

Outline of File Kinds

This is where you make changes to the file kinds hierarchy.

User the + and - buttons below the outline to add or remove new file kinds. Use drag&drop to move a file kind to a new parent. Double click to rename a file kind.

Extensions

To the right of the file kinds outline you’ll see the extensions associated with the selected file kind.

Extensions directly associated with the selected file kind are represented as blue tokens. You can edit and remove them. Type a new extension in here and press enter to add a new extension.

A file kind with subkinds will also show the extensions of all its descendents. Those tokens have a grey background color and cannot be edited or even selected. Chage them in the file kind they have been defined in.

Updates / License

Here you can check for updates manually and enter/review you license information.

Search History

Every time the search window is closed while a search query is entered in the searhc field GoToFile stores the query in its history. You can navigate the history in every mode operating on files by pressing ⌃P (previous item) and ⌃N (next item). While navigating the history you can press ⌃⌫ to remove the currently displayed query from the history and bring up the previous item.

You can also enter the History Mode (⌘H) to get a searchable list of the previously entered queries.

The Search History will remember the last 100 items. It is persisted across application restarts.

Finder Integration

Search Folder

1. Select the folder in Finder
2. Select “GoToFile: Search” from the Services menu

This action creates an ad-hoc project from the selected path and sets it as the current project.

Browse Folder

1. Select the folder in Finder
2. Select “GoToFile: Browse” from the Services menu

Find Similar Items

1. Select an item in Finder
2. Select “GoToFile: Find Similar Items” from the Services menu

This action searches for items matching the name of the selected item in the currently active project.

Controlling GoToFile from the Command Line

GoToFile includes scripts to browse and search a path from the command line.

Installation

The two scripts gtfs and gtfb are contained in the GoToFile application bundle. If GoToFile has been installed in the Applications folder, the scripts can be found in /Applications/GoToFile.app/Contents/Resources/bin. You can either copy them from there to a location in your $PATH or set your $PATH to include this directory.

Search Folder

When gtfs is called without arguments, it will bring up GoToFile’s search panel and set the current working directory (cwd) as the Ad-hoc project. The search string will be empty. gtfs supports four optional command line arguments:
     --path=STRING: The path of the Ad-hoc project
     --project[=STRING]: The project you want to search; if no project is specified, the currently active project is assumed.
     --query=STRING: The search string
     --help: Prints gtfs [[--path=]STRING|--project[=STRING]] [--query=STRING]

gtfs --project=Home --query="myfile"

gtfs --project --query="myfile"

gtfs --query="myfile"

Browse Folder

When gtfb is called without arguments, it will bring up GoToFile’s search panel in Browser Mode and set the current working directory (cwd) as the current path. The search string will be empty. gtfb supports three optional command line arguments:
     --path=STRING: The path to browse
     --query=STRING: The search string
     --help: Prints gtfb [[--path=]STRING] [--query=STRING]

gtfb ~/Downloads --query="myfile"

Keyboard Shortcuts

Navigation

General

Mode Specific

The mode column indicates in which mode the keyboard shortcut works: Search, Browse, Marked Items, Recent Items, Projects, History.

Mode Specific While an Item is Selected

These actions are performed on all currently selected items or, if a path component of the selected item is highlighted, on the highlighted path component. See Selection for details.

If the current mode is Projects the actions are performed on the search folder configured for the selected project. Should the selected project consist of multiple search folders these actions will fail.

The mode column indicates in which mode the keyboard shortcut works: Search, Browse, Marked Items, Recent Items, Projects, History.

Terminology

Index

The index is a database which helps speeding up the search process. The database is held entirely in memory. It is populated whenever a project/folder is selected for the first time after the program starts. Later on the database is updated in the background whenever changes are made to the file system.

Project

A project is a collection of folders to search. It also defines how these folders are searched and which items should be stored in the index. Projects are configured in the Project Editor.

Ad-hoc Projects

An ad-hoc project is like a project containing only a single directory to search, but it is not created (or visible) in the Project Editor or in the Project Selector.

Ad-hoc Projects are created by
- searching a directory by pressing ⌘⇧S while a file or folder is selected
- using the command line utility gtfs without the --project argument or with the --path argument
- using the Search Folder or Find Similar Items

When searching an ad-hoc project the Info Bar will display ‘Search directory …’ instead of ‘Search project …’. Press ⌘P twice to switch back to the previous project. Closing the search panel via ⎋ with an ad-hoc project active will switch back to the most recent “regular” project for the next search. Pressing ⌘W will also close the window but leave the ad-hoc project active.

Selection

In every mode the selection is the item selected in the result table. Actions operate on the selection. In Search Mode, Recent Items Mode, and Marked Items Mode you can further choose which part of the path is considered for actions. Use ⌃, and ⌃. to select different parts of the selected items path. Once part of the path is highlighted actions will operate on this path component instead of the full path. The selection icon reflects this change. Clear the highlighting by either selecting a different item of by using the Clear Highlight (⌃/) command.

Executable

The term “executable” refers to any script or binary which can be executed from the command line.

Major Mode

One of the major modes of operation of GoToFile: Search, Browse, Recent Items, Marked Items. Major Modes operate on files.

Minor Mode

Minor Modes provide utility functions. They do not operate on files but display a searchable list of arbirary data which the user can act upon: Project, History, Actions, Data Provider.