Git Style Configuration

TextMate 2 isn't just about adding a ton of killer new features. It's also about throwing out what just plain didn't work. That means you can kiss the old project files goodbye.

Of course, you throw out bad ideas so you can replace them with good ideas.

Project files serve a couple of purposes in TextMate 1. One was to give you access to folders you commonly work with. That's now handled through TextMate 2's File Browser and we're going to talk a lot more about that in the future. Another purpose though was to support project level configuration. Configuration is a great idea, but the old interface was awkward and inflexible.

TextMate 2's new .tm_properties files address this need, similar to .git configuration files.

In this article we'll discuss:

  • The various places TextMate 2 will look for configuration settings
  • Examples of some settings you may wish to tweak
  • Per file type configuration
  • Dynamic project based configuration

Project Settings

Enough about the why, let's get to the how.

To start configuring project level options in TextMate 2, just dump a .tm_properties file in the root directory of the project and type your settings right in there. If you already have the project open in TextMate 2, the easiest way to get to this file is to just select Preferences… from the File Browser's action menu.

Selecting Preferences in the File Browser

By way of example, let's say you have a project of documentation files. You could dump the following settings into a .tm_properties file at the root of that project:

TM_GIT = "/usr/local/bin/git"

fontName = "DejaVu Sans Mono"
fontSize = 14

[ "*.{txt,md,mdown,markdown}" ]
softWrap = true

The above shows the three kinds of things you can configure. First, you can set TextMate variables, as I did with TM_GIT. The Git bundle helps me manage my commits while staying inside TextMate, but it needs to know where the git executable is installed to do that. It assumes a MacPorts install location by default, so I just redirected it to my Homebrew install here.

The second section shows how to set TextMate settings. Here I've entered the fontName and fontSize I prefer to work with.

The third section also configures a setting, but it shows how you can restrict settings to certain file types. In this case I've used a shell glob to specify that this setting be applied to files with a plain text or Markdown extension. I want to wrap those files, but not any other code files that may be in the project.

TextMate 2 will apply these setting when working with any file under the project folder. Different projects can have different settings per your tastes.

From Folders to Global Defaults

Now, as you probably already figured out, these files don't have to be project wide settings. It's just a file in a folder as far as TextMate 2 is concerned and it will always affect every file below it. Given that, you can adjust the settings for just part of a project, by adding a .tm_properties file to that folder. You might apply some settings to the project as a whole, but then override them for the doc folder, for example.

This works because TextMate 2 walks up the current file path, looking for .tm_properties files. All of those settings apply, with lower files overriding higher files as needed.

The search stops with the current user's home directory (~) or the root directory (/). However, if the root directory is reached, the current user's home directory is added to the search above it. This makes it possible to create a ~/.tm_properties with global default settings that always apply, even if you edit files outside of your home directory.

Smart Settings

You can accomplish some pretty cool voodoo by playing with these configuration files. For example, here's some of the project settings used to build TextMate 2:

TM_MAKE_FILE = '${CWD}/Makefile'

[ "tests/*.{cc,mm}" ]
scopeAttributes = 'attr.test.cxxtest'
TM_MAKE_TARGET  = '${TM_FILEPATH/^.*?([^\/]*)\/tests\/.*$/$1/}/test'

The first thing you should notice here is that we are allowed to use TextMate variables, as well as set them. This allows us to configure the project's Makefile using $CWD (for current working directory). This works because the .tm_properties file is in the root directory of the project and that will be the value of $CWD.

The Make target for the TextMate 2 project is set elsewhere (not shown), but we see another use of variables to override it for the tests on the last line here. Note that it's possible to use regex replacements on these variables, just as we could in a snippet.

Finally, the powerful scopeAttributes setting is used here to add a scope to all content in the testing files. This is also helpful for the activation of special snippets when working in these files.

As you can see, it's possible to show TextMate 2 how you want to work with each of your projects. You could even set which language files should be spellchecked in, on a folder by folder and/or file type basis.

The Settings

A list of the available settings is available as well as a guide with more information.