Projects

When opening a folder, TextMate will treat the items within this folder as belonging to your project for actions such as Edit → Find → Find in Project… (⇧⌘F), File → Open Quickly… (⌘T), and many of the bundle commands, such as Bundles → TODO → Show TODO List (⌃⇧T), or any of the actions in the Bundles → SCM submenu.

If you need to include files in your project that exist outside the enclosing folder, you can create a symbolic link that points to your other files.

By default TextMate will not follow symbolic links or show them as expandable in the file browser, but this can be changed:

• File Browser: Enable “Show links as expandable” under Projects in TextMate → Preferences… (⌘.)
• Find in Project: Check “Symbolic Links to Folders” in the gear pop-up menu.
• Open Quickly: Set followSymbolicLinks to true via the properties system.

Filtering Files

There are a few ways to filter unwanted items from your projects.

The simplest is to alter the “Exclude files matching” and “Include files matching” glob strings shown under Projects in TextMate → Preferences… (⌘.)

For an item to be shown in the File Browser, Open Quickly, and Find in Folder dialogs, the item must match the include glob string and must not match the exclude glob string.

Furthermore, items matched by the “Non-text files” glob string will not show up in Open Quickly, nor will they be searched by Find in Folder, unless you check the “Binary Files” menu item in the gear pop-up menu.

By default * does not match dot-files, that is why the default include pattern is set to {*,.tm_properties,.htaccess}, so we start by including all files that does not start with a dot, and then additionally .tm_properties and .htaccess.

If you have other dot-files that you would like to show, then we recommend adding them to this list.

After the item has been tested against the include pattern, it will be tested against the exclude pattern. The default exclude pattern is {*.{o,pyc},Icon\r,CVS,_darcs,_MTN,\{arch\},blib,*\~.nib} which hides a lot of items that you would normally not be interested in seeing.

If you have other files or folders that should generally be hidden (regardless of project) then you can add them to this list.

The Find in Folder dialog has its own “matching” glob string which is in addition to the above and remembered per project. This serves as a quick way to change what files are searched. Worth pointing out that glob strings support negation/exclusion, so to quickly skip searching a logs folder, you can set the “matching” glob string to ~logs/** or for a more complex example you can set it to *.{html,css,js}~caches/**~logs/** to search files with an .html, .css, or .js extension, except those that are descendents of the caches or logs folders.

For more complex filtering needs, the following settings are available via the properties system:

Component	Any Item	Directory Items	File Items
All	include	includeDirectories	includeFiles
All	exclude	excludeDirectories	excludeFiles
File Browser	includeInBrowser	includeDirectoriesInBrowser	includeFilesInBrowser
File Browser	excludeInBrowser	excludeDirectoriesInBrowser	excludeFilesInBrowser
Open Quickly	includeInFileChooser		includeFilesInFileChooser
Open Quickly	excludeInFileChooser	excludeDirectoriesInFileChooser	excludeFilesInFileChooser
Find in Project	excludeInFolderSearch	excludeDirectoriesInFolderSearch	excludeFilesInFolderSearch

For a project, it is common to exclude certain folders in Open Quickly and Find in Folder, but keep them visible in the File Browser, so a typical .tm_properties for your project could look like this:

excludeDirectoriesInFileChooser  = "{caches,logs,vendor}"
excludeDirectoriesInFolderSearch = "{caches,logs,vendor}"

Be aware that for Find in Project and Open Quickly the settings are currently only read for the start folder, and will not be updated for subfolders, that is, if you have a folder structure like the following:

.
├── .tm_properties
├── ⋮
└── src
    └── .tm_properties

Then TextMate will use the settings from the top-level .tm_properties file and start the scan, but once it descends into the src folder, it will not update the glob patterns with potential new values from the nested .tm_properties file.

Project Folder

When you open a folder in TextMate, it becomes the “project folder” and Open Quickly show only files within this folder, likewise Find in Project will use this folder as starting point, and the folder is exposed to commands as the TM_PROJECT_DIRECTORY environment variable, so many bundle actions will also use this folder as what to work on.

Though for bundle items the convention is that if there is a selection in the File Browser then this is preferred over the project folder.

For Edit → Find → Find in Project (⇧⌘F) it will use the File Browser selection only if the File Browser has focus when invoking the action, or if pressing the search icon located in the File Browser’s toolbar.

If you wish to change the project folder then navigate to the desired project folder in the file browser and click the path drop-down at the top. In this menu you can select “Use «folder» as Project Folder”.

If you are unsure what is currently set as your project folder, you can invoke File Browser → Project Folder (⇧⌘P), though by default, the name of your project folder should be part of the window title.

It is worth mentioning that File Browser → Enclosing Folder (⌘↑) also work in Open Quickly and Find in Project.

Window Title

The window title contains the document name, the name of the project folder (if any) and the current branch, if the project is using a version control system that supports branches. This is done via the properties system using the windowTitle setting, here are the default settings:

windowTitleSCM     = '${TM_SCM_BRANCH:+ ($TM_SCM_NAME: $TM_SCM_BRANCH)}'
windowTitleProject = '${projectDirectory:+ — ${projectDirectory/^.*\///}}'
windowTitle        = '$TM_DISPLAYNAME$windowTitleProject$windowTitleSCM'

If you wish to change the title you can make use of the two windowTitleProject and windowTitleSCM variables to optionally include project and version control info in your custom title.

For example, if we want to show the path as relative to the project folder, we can use:

windowTitle = '${TM_DIRECTORY:+${TM_DIRECTORY/^${projectDirectory}(?:\/(.+))?/${1:+$1/}/}}$TM_DISPLAYNAME$windowTitleProject$windowTitleSCM'

Default File Type

Under Files in TextMate → Preferences… (⌘.) you can set “New document type” which is used by actions such as File → New (⌘N) and File → New Tab (⌥⌘N).

If you wish to change the setting for a certain folder then you can use the properties system and set the fileType setting scoped to attr.untitled. For example if you wish the default file type to be html for files created in /path/to/project/html then create /path/to/project/html/.tm_properties and have it contain the following:

[ attr.untitled ]
fileType = "text.html"

When you create a new file with File → New (⌘N) or File Browser → New File (⌃⌘N) then TextMate defaults to using the root folder of the file browser, and thus this is the folder consulted for folder specific settings, however, if you have a folder selected in the file browser, TextMate will use this folder instead if, and only if, the folder is expanded. If you have a file selected, it will use the enclosing folder of this file.

Creating Tabs

Most ways to open a file inside TextMate will make it open as a new tab in the current window. Files opened from outside TextMate will open as a new tab, if the file is a descendent of an existing window’s project folder, or if a project has been explicitly requested for the file being opened. The latter is possible using mate and setting the TM_PROJECT_UUID environment variable, something that is implicitly done when mate is called by a command running inside TextMate, meaning bundle commands that open new files will normally open these as tabs in the existing project.

If you want to force mate to open a file in a new window, you can set an all-zero TM_PROJECT_UUID, for example:

TM_PROJECT_UUID=$(uuidgen|tr [0-9A-Z] 0) mate /path/to/project/file

Selecting Window → Merge All Windows will move all open documents in non-minimized windows to a single window (with tabs). Excluding minimized windows can be used to merge just a few windows: minimize the windows that should be left alone, and then select the action.

Once a file has been opened in a new tab, it is possible to move it to a new window by selecting Window → Move Tab to New Window, by selecting the same action in the tab’s context menu, or by double-clicking the tab.

Tabs can also be dragged between windows but if dropped outside the tab bar of an existing TextMate window, the drag will act as if the file itself was dropped, rather than create a new window for the document. This is useful when you need the path of a document inserted into your terminal, as you can then drag and drop the desired tab to the terminal window.

Closing Tabs

A common problem is being left with too many open tabs. In an attempt to counter that, TextMate will automatically close tabs that hasn’t been used in a while, when the tab bar overflows.

This feature can be disabled by running the following in a terminal:

defaults write com.macromates.TextMate disableTabAutoClose -bool YES

Additionally there are a few explicit ways that you can close multiple tabs in a single action:

• Hold down option (⌥) when opening a file either via the file browser or open quickly. For the latter, you normally open files via return (↩) so here you would press option-return (⌥↩).
• Use File → Close Other Tabs (⌃⌘W) or File → Close All Tabs (⌃⌥⌘W).
• Right-click a tab and select any of the close actions, e.g. Close Tabs to the Right.

Sometimes you have documents that should stay open, like your project’s to-do list. In this case, right-click the tab in question and check the Sticky option. When a tab is made sticky, the batch close actions will leave it open.

File Browser

Opening files from the file browser is done by single-clicking the file’s icon, double-clicking the file name, or using command-down (⌘↓) when focus is in the file browser.

On the Projects page of TextMate → Preferences… (⌘.) you can enable “Open files on single click”, but enabling this does mean that using the file browser to make selections, prior to committing files or similar, becomes more complicated, so it is not an option we recommend using.

Descending into file packages or application bundles can be done either by selecting Show Package Contents from the context menu, or by holding option (⌥) while double-clicking the item or single-clicking the item’s icon.

If command (⌘) is pressed while single-clicking an icon in the file browser, then the clicked item will be shown in Finder. The same functionality is also available from the context menu as “Show «file» in Finder”.

Location and Selections

Many commands use the file browser selection as the set of files to work on, for example if you wish to see uncommitted changes for a subset of files, select those files before invoking the version control command. If there are no selection, the commands will generally work on the entire project.

For this reason, it is useful to learn the following two shortcuts:

1. File Browser → Select «document» (⌃⌘R) which will reveal and select the current document in the file browser.
2. File Browser → Select None (⇧⌘A) which will deselect all selected items.

So for example, if you have selected items in the file browser and wish to bring up the commit window “for the entire project”, first press ⇧⌘A to deselect all. Likewise, if you wish to see uncommitted changes for only your current document, press ⌃⌘R first.

In the File Browser menu you can also find a few other useful actions for changing location. Be aware that the key equivalents of File Browser → Back (⌘[), File Browser → Forward (⌘]), and File Browser → Go to Folder… (⇧⌘G) are only available when focus is in the file browser, and due to system limitations, will not show in the menu.

The File Browser → Enclosing Folder (⌘↑) action is available for the file browser, but also open quickly and find in folder.

Moving and Copying Items

Drag and drop can be used to move items from one location to another. Holding down command (⌘) will change the move action to perform a copy and control (⌃) will create a symbolic link to the item being dragged at the drop location.

With focus in the file browser it is also possible to use Edit → Copy (⌘C) followed by Edit → Paste (⌘V) to create a copy.

By using ⇧⌘V instead of ⌘V the paste action will be changed to move.

The file browser action menu has Duplicate (⌘D) which will duplicate the selected items. By default copy will be appended to the duplicate, but if the name starts with YYYY-MM-DD then TextMate will instead replace this prefix with the current date.

If you drag an item to the text view and hold down control (⌃) then the full path of the item will be inserted as text.

Keyboard Usage

Moving keyboard focus to the file browser can be done by selecting Navigate → Move Focus to File Browser (⌥⌘⇥). Use the same action to move focus back to the document.

When focus is in the file browser, the following key equivalents can be used.

Key Equivalent	Action
⌘↓, ⌘O	Open selected item(s)
Space	Quick Look selected item(s)
↩	Rename selected item
⌘D	Duplicate selected item(s)
⌘X, ⌘C	Cut or copy selected item(s)
⌘V, ⇧⌘V	Paste item(s) using copy or move
⌘⌫	Move selected item(s) to trash
⌘Z, ⇧⌘Z	Undo or redo last action
⌥⌘I	Show hidden files
⌘[, ⌘←	Go back in history
⌘], ⌘→	Go forward in history
⌘↑	Go to enclosing folder
⇧⌘G	Go to folder…
⇧⌘F	Search selected item(s)
⌥F2	Show context menu

Using Edit → Cut (⌘X) will not remove the item before it has been pasted somewhere else. To immediately remove an item, use Edit → Delete (⌘⌫).

Effective Folder

Actions like File Browser → New File (⌃⌘N) require a folder which is obtained from the file browser in this way:

If something is selected, the folder containing the selected item(s) will be used as the effective folder, unless a single expanded folder is selected, in this case, the selected folder is used. If nothing is selected, the top folder showing in the file browser is used.

Custom Commands

It is possible to add your own commands to the file browser’s action menu.

This is done by creating a bundle command and setting its semantic class to callback.file-browser.action-menu.

An example of a command that appear in the file browser’s action menu is Bundles → Shell Script → Open Terminal (⌃⇧O). The Compress Selected Items and Show Images are also bundle commands.