10.8 2.0%
10.7 86.7%
10.6 11.1%
10.5 0.2%

With such a small percentage on 10.5 it makes sense to drop its support. Moving forward we may decide that requiring Lion will be a reasonable tradeoff as it provides many underlying benefits we could take advantage of. The usage statistics will be monitored to determine the feasibility of this move.

Also to help answer many of the more commonly asked questions we've put together a FAQ about 2.0.

class BoundingBox
  def initialize(min_x, min_y, max_x, max_y)
    @min_x = min_x
    @min_y = min_y

    @max_x = max_x
    @max_y = max_y
  end
end

I could later use completion to finish off this line:

class BoundingBox
  def max_x=(x)
    fail "max_x must be > min_x" unless @m‸
    # ...
  end
end

If I push ⎋ where my caret currently is (shown with ‸ above), TextMate will complete the variable reference to @max_y. It starts with @max_y, because that's the closest instance variable reference to my caret (from the bottom of initialize()), meaning it had a high chance to be what I was referring to. It's not really what I wanted though, so another press of ⎋ cycles me to the second choice of @max_x. That is what I want, so I add > and another @m. Then I can complete until I get @min_x (four presses of ⎋ or just one press of ⇧⎋ to go backwards, since it's the furthest reference from my caret).

In this article will discuss:

• Reasons to use completion
• Suffix completion
• Prefix completion
• Mid-word completion
• Intelligent scoped completion

Already Better

The previous example pretty much worked in TextMate 1 and it's definitely still around in TextMate 2. I say "pretty much" because this example is already showing off how much smarter TextMate 2 is when it comes to completion.

You see, TextMate 1 had a pretty fixed idea of what a "word" really is and, since completion works on words, it wasn't super clever. By default, it would have ignored the leading @ that identifies an instance variable and just started completing m words. That means the first sequence would have gone min_x, must, and then max_x (since those are the closest to my caret). Because TextMate 2 did use the @ it got to the right answer in one less step. In bigger examples it could save even more cycling. This actually turns out to be a big change with some pretty sweeping implications for TextMate 2 and we'll get to those, but first let's take a few detours…

Why use completion?

I bet some of you are wondering if completion is really worth an article all by itself. Frankly, it is.

Programming is hard enough all on its own, so anything that can make it easier is a win. The fact is that completion reduces errors. You're just less likely to typo a variable or method name while using it. Since TextMate is often used for dynamic languages, like Ruby which silently uses nil for newly referenced instance variables, this becomes doubly important.

Make friends with your ⎋ key.

TextMate 2 is Now on the Right Side

Completion in TextMate 1 only used content to the left of the cursor. In other words, it finished typing words. TextMate 2, now uses the left and right sides. What does that give us? Well, prefix completion for one thing.

Say I'm still finishing off that method we looked at earlier and I make a mistake entering it:

class BoundingBox
  def max_x=(x)
    fail "max_x must be > min_x" unless @max_x > @min_x
    ‸x = x
  end
end

I meant to type @max_x = x there, instead of x = x. I run my tests, they catch the bug, I come back and notice the problem. Prefix completion makes the fix trivial. I click in front of the first x and push ⎋ until it fixes the variable reference (two times for this case).

Selecting What You Don't Want

Technically, TextMate 2 uses the content to both the left and right of the caret for completion. This means you can also do a mid-word completion. I can type an @m_x, stick my caret between the m and the _, and push ⎋ to rotate between @max_x and @min_x (with the order determined by what's closest to my caret).

I know what you're thinking though. It's kind of a contrived example, right? When are you going to use that?

Well, it turns out that TextMate 2 has another trick up its sleeve that just might change your mind. I said that it uses what's to the left and right of the caret, but I left out a detail. It also removes any selection.

Knowing that, let's say you used @min_x somewhere when you meant to use @max_x. Again, your tests catch the bug. Good thing you have those tests! So you go to fix it. One possible solution is that you click behind the n, press ⇧⇠ twice to select in, and push ⎋ to make the correction. It's guaranteed to be just one press of the ⎋ key this time too, because, even thought TextMate 2 removes the selection to make the completion, it does use it to filter out the choice you didn't want. Thus @max_x will be the only matching variable in our code with @min_x ruled out.

Are you keyboard jockeys scoffing at my use of the word "click" above? Alright, let's get fancy. If your caret is just after a @min_x you wish to change to a @max_x, try this: press ⌃⇠ to jump over a sub-word chunk (the x in this case), then ⌃⇧⇠ to jump over the next sub-word chunk (min_) while selecting it, and finish the maneuver off with an ⎋ to make the correction. (Note: if the OS swallows those sub-word bindings for Mission Control or Spaces, just add an ⌥ (option) to them: ⌃⌥⇠ and ⌃⌥⇧⇠.) The m and the _ don't change the result, so that's a three-keystroke correction that's guaranteed to be exactly what you want.

It's All About Character and Class

Let's go back to that concept of a word that I talked about earlier. I said all of this works because TextMate 2 has an improved idea of what is in a word. In truth, TextMate 2 can assign named grouping to any set of characters. As is usually the case, this concept of character groups is managed by scope, allowing TextMate 2 to adapt to multiple languages.

Ruby considers @max_x to be a set of variable characters (with the @) because the Ruby bundle scopes it as variable.other.readwrite.instance.ruby. That scope is inside of the scope source.ruby so it inherits this magic setting from the Source bundle:

{ characterClass = 'variable'; }

That setting is scoped to variable, so it affects everything under that distinction. In plain English it says, inside of source code files, treat variables as a group of related characters. A Ruby instance variable includes the leading @, so it's in the same group of characters as letters that follow it. Global variables and their leading $ (in Ruby) would be treated the same.

But the real question is, what else does TextMate 2 consider to be related in code files? Several things, including my personal favorite:

{ characterClass = 'escape'; }

That's scoped to constant.character.escape, which means that escape sequences are now self contained chunks of characters separate from the content around them.

What can we do with that? Well, say we have this simple Ruby statement:

lines = "‸Just\nTesting"

That string contains three words as far as TextMate 2 is concerned. That's not just for completion either. If I place the caret at the beginning of the string and use ⌥→ to jump forward by words, I'll skip to the end of Just, \n, and then Testing. Compare that to TextMate 1, which considered Just and nTesting to be words with a little punctuation (\) between them.

But this article isn't about movement, as cool as it is. It's about completion. So let's add a little more code:

lines = "Just\nTesting"
if lines =~ /\bTe‸/
  # ...
end

If we push ⎋ with our caret after the Te, TextMate 2 will complete Testing from the string above. Notice how much context it's using to make this decision. We're inside a Regular Expression here, so TextMate 2 knows the word boundary escape (\b) isn't part of the word to complete (Te). It also looks for possible completions inside of that Ruby string, where it knows the newline escape (\n) isn't part of the matching completion (Testing).

Augmented Completion

If that's not enough for your completion needs, you can augment the command yourself. TextMate 2 also takes this option one step further by passing the entire document to completion commands on stdin.

That's some clever completion, if you ask me!

In this article we will discuss:

• The syntax of TextMate 2's Format Strings
• Where you can use them
• The kinds of tricks these tools can help you accomplish

Titling Your Work

We've already discussed .tm_properties files and how you can use them to customize TextMate 2's behavior. What I didn't tell you before though is that those settings are Format Strings.

One option you can customize is the title used for the editing window. By default, the window title shows the name and extension of the file you are editing. Let's use some Format String magic to fancy that up.

First, I can just add this option to the .tm_properties in my home directory to also show the directory of the file being edited:

windowTitle = "$TM_DISPLAYNAME – $TM_DIRECTORY"

This is useful to me if I am editing in a project where it's common for files to have the same name, but be located in different places. Rails applications are like that.

However, the full paths can get pretty long. If you want something shorter, we can edit the variable as it is used with a Regular Expression:

windowTitle = "$TM_DISPLAYNAME – ${TM_DIRECTORY/([^\/])[^\/]+\//$1…\//g}"

That expression is a little difficult to read because it's matching directory separators, which are the same characters TextMate uses to delimit a Regular Expression. The first chunk between the non-escaped / characters (([^\/])[^\/]+\/) is the expression which searches for two or more character directories with a trailing /. The replacement string ($1…\/), before the next unescaped /, just truncates the directory down to the first character, an ellipsis, and the trailing separator. The final g after the last / turns on the global option for the replacement, so we trim all the directories but the last (because it won't have a trailing / to match).

Obsessive Compulsive Window Titles

Note: the following example is real world and may get pretty complex. Lighter example follows.

I like the trimmed paths, but I'll be honest and tell you that's not my actual windowTitle setting. Here's what I really use:

windowTitle = "$TM_DISPLAYNAME${TM_DIRECTORY/\A(?:\/Users\/james\/Documents\/(?:work\/)?(?!\b(?:communication|programming|reference)\b)\w+\/?(.*)|(.+))\z/${2:? – ${2/\/Users\/james/~/}:${1/\A(?=.)/ – /}}/}"

This leads us to two of the great features of Format Strings in TextMate 2: the replacement of a variable reference is a nested Format String and you can branch based on whether or not a variable is set. This allows your to run replacements on a replacement and choose between multiple replacements. Let me explain how I use those in the pattern above.

I keep my current project directories just inside of ~/Documents. I also move older projects into a ~/Documents/work subdirectory. I want to see paths inside of those project directories, but I don't need to be reminded that they are in ~/Documents or ~/Documents/work. I also don't need to see the project directory itself, since I'm seeing that in the File Browser. Other non-project directories should be handled normally. There are also a few directories inside ~/Documents that aren't project directories and those should be treated like any other directory.

For example, here are some path transformations:

• ~/Documents/tm2_documentation/ is stripped
• ~/Documents/tm2_documentation/calendar/ becomes calendar
• ~/Documents/work/scout/ is stripped
• ~/Documents/reference/documentation/ is not changed

Given that, I just do a search for a leading (\A) followed by either ((?:…|…)) hardcoded path (\/Users\/james\/Documents\/), the optional work directory ((?:work\/)?), followed by a project directory name that isn't one of the exceptions ((?!\b(?:communication|programming|reference)\b)\w+\/?), and anything that happens to be trailing that ((.*)) or any other directory listing ((.+)) anchored to the end of the path (\z). That's the easy part, but the replacement is where we get tricky.

To understand the replacement, you have to understand the desired result. If I have a file open from just inside the root project directory, I only need to see that file's name. For example, Gemfile. However, if I have a file open deeper in the project, I want to see the name and the path from the project's root directory. An example of that would be show.html.erb – app/views/users. The gotcha is the separator (–). I don't want the separator if it isn't going to be followed by a directory. Non-project directories can just show the full directory path, but it would be nice to at least shorten /Users/james to ~ for them.

To accomplish that, I first check to see if I'm in a project path or a normal (${2:?…:…}). When it's a normal path, $2 will be set because that's the part of the expression that matched them. If it is set, I prepend a separator and run a replacement to alias my home directory as discussed above (– ${2/\/Users\/james/~/}). If this is a project path, I run another regex replacement on $1. If the beginning of it (\A) is followed by an unmatched non-newline character ((?=.)), I replace that beginning (no content, just an anchor) with a – to get my separator.

While the above was all about aesthetics, there are other variables, like TM_MAKE_TARGET, that can likewise benefit from a path-derived value. There's an example of how this can be used in the article on .tm_properties files.

Replacing a Replacement

While the previous example is just a scary showing of how far I will go to keep my windows looking pretty, the features used have a lot of powerful and practical applications.

Nesting Format Strings allows for pretty clever uses of the Find and Replace dialog. Want to convert a single-quoted Ruby string literal into the double-quoted variety while adding the proper escaping? Just Find for the regex '(.*?)' and replace with "${1/"|#\{/\\$0/g}". Try that out on this chunk of Ruby:

'a "simple" string with no #{interpolation}'

and it will be replaced with:

"a \"simple\" string with no \#{interpolation}"

This works because the second search hunts inside of the original string content ($1) for things that need escaping (" and/or #{) and prepends the escape (\\) to them.

This or That

The other feature I made use of earlier was if/else variable replacements. Again, this is a handy transformation tool.

Let's say we have some CSV content:

Product,Price
iPhone 4S,$199.00
MacBook Pro,"$1,199.00"
"Mac OS X ""Lion""",$29.99

We could convert that to tab-separated content and strip the extra quoting (we're confident there are no tabs in the fields) as we go, with just one Find and Replace operation. The Regular Expression used in the Find is \G(?:"((?:""|[^"]*)*)"|([^,]*))([,\n]) and the replacement is ${1:?${1/""/"/g}:$2}${3/,/\t/}.

Let's talk through how that works, because it's pretty instructive.

The idea with the regex is that we need to walk through the data one field at a time. We do that by saying: pick up where the last match ended or at the beginning for the first match (\G) and look for either ((?:…|…)) a quoted field "(…)", which is zero or more escaped quotes and/or runs of non-quote characters ((?:""|[^"]*)*), or an unquoted field (([^,]*)) delimited by a comma or a newline (([,\n])). Each time that pattern matches either $1 will be set with the contents of an quoted field or $2 will be set with the contents of and unquoted field. No matter what $3 will be set with a comma or a newline. That sets us up for the replacement work.

The replacement string has two branches. If $1 is set (${1:?…:…}), then use the quoted content, but unescape all quotes first (${1/""/"/g}). Otherwise, use the unquoted content ($2). Either way, add the separator at the end, but switch commas to tabs (${3/,/\t/}).

Bundled Ifs

The ${VARIABLE:?…:…} form is useful when you need an if clause and an else clause. If you only need the if you can use ${VARIABLE:+…} and you can use ${VARIABLE:-…} for else-only insertions.

A good example where this shortcut style is used involves setting a shell variable inside the Themes bundle:

shellVariables = (
  { name = 'TM_THEME_PATH';
    value = '${TM_THEME_PATH:+$TM_THEME_PATH:}$TM_BUNDLE_SUPPORT/web-themes';
  },
);

This prepends an existing path, if it already exists before it is set here. This allows one command, like Web Preview in the Support folder, to read an environment variable (TM_THEME_PATH) and learn about the paths of third party bundles.

Bundle completionCommand settings are also Format Strings.

The Case for Replacements

Another form of Format Strings allows you to change the case of a variable reference. If you combine that with the fact that scope name elements in TextMate 2's Language Grammars are now Format Strings, this allows for nice dynamic scoping tricks.

For example, say we rework Ruby's "here-document" (heredoc) syntax rule to look something like this (simplified) example:

begin = '<<-?(\w+)';
name  = 'string.unquoted.${1:/downcase}.ruby';
…

That would mean that a heredoc definition like this:

<<-CSS
body {
  margin: 10px auto;
}
CSS

would be scoped as meta.here-doc.css.ruby. This allows the injection of the CSS Grammar and automations into the scope meta.here-doc.css. That would mean that you get the proper syntax highlighting of these heredocs and you could trigger CSS Bundle commands while editing them.

As I write this, the ruby grammar still has a dozen rules with a dozen different tokens that include a dozen different languages, so the above is a planned simplification that would allow us to avoid having to upgrade the ruby grammar for new potential here-doc tokens.

The supported case transformations are /upcase, /downcase, and /capitalize. There's also a special /asciify transformation that will transliterate things like "æ" and "ø" into "ae" and "o" respectively as well as remove any remaining non-ASCII characters. The latter is particularly useful when deriving an identifier or label, that needs to be accepted by a language parser, from a heading or comment, which is free-form prose. These transformations can be combined.

A Tiny Snip of Snippets

Format Strings also have some Snippet-only enhancements, like the new pop-up choice syntax. We'll cover those in an upcoming article on what's new with Snippets.

In the meantime though, I will give you one fix TextMate 2 has over its predecessor. If you need to place a literal number right after a numeric variable reference you can now use this form: ${1}337. That works in Snippets and anywhere else Format Strings are used: .tm_properties files, Find replacements, Language Grammar name fields, and Bundle Settings.

In TextMate 2, mate has learned some new tricks. A new partner-in-crime has also been introduced: rmate.

In this article will discuss:

• How to install the upgraded mate
• mate's new features
• What rmate is
• The different ways to use rmate

Upgrade Time

Once you have TextMate 2, you need to make sure you refresh the command-line mate application. This allows you to take advantage of its new features.

The installer of this command-line utility has moved in TextMate 2. You can now find it in the TextMate menu under Preferences… in the Terminal pane.

To install or upgrade mate, just select a Location and hit Install. You may be prompted to Replace an old version, if present.

This pane can later be used to uninstall the command if you need to do that.

Users usually install mate into ~/bin if they just need it for the current user and /usr/local/bin if they would rather make it accessible to all users (assuming they have /usr/local/bin in their PATH). If you would like to find where your TextMate 1 version is before you upgrade, feed your Terminal this command: which mate.

Your New mate

Let's get to the good stuff. What's upgraded in mate?

First, it's a small tweak, but you will be happy to hear that mate now works with sudo. You can use this to edit restricted access files in TextMate 2 without being bothered by an authorization dialog on save:

sudo mate /etc/hosts

Next, mate has picked up some new command-line options. One is -t, which allows you to set the type of an opened file. Personally, I like this feature for README files, which I prefer to write in Markdown. Since the name of standard files like this don't always include an extension, we can just tell TextMate 2 how to handle the file as we open it:

mate -t text.html.markdown README

Another new option is --name. This allows you to set TM_DISPLAYNAME which is typically shown in the title bar on TextMate's windows. For a good use of that, let me share a line from my Bash configuration:

export GIT_EDITOR="mate --name 'Git Commit Message' -w -l 1"

The -w and -l options have been around for a while. -w just tells TextMate to wait for the edit to finish. That's what allows you to use the command as an external editor for tools like Git that are waiting for an answer.

-l just tells TextMate to place the caret on the indicated line. I force the first line here because Git has a habit of reusing commit message files and TextMate would otherwise try restore the caret to it's last location. Since that last location was probably at the end of a message that's changed or no longer present, the caret would likely be left in the middle of Git's comments. That's not too helpful for a quick edit, so -l 1 forces the caret back to the beginning.

That leads us, finally, to the new option used above. Since Git will just use some file like .git/COMMIT_EDITMSG, our window isn't going to have the best title by default. This use of --name clears that up by telling me exactly what I'm looking at.

Selection Strings

I mentioned before that TextMate 1's version of mate supported -l. That's true, but -l is far more powerful in TextMate 2 and that new power has spread to other commands.

With the old version of mate, -l was super simple. It just took a number and it took you to that line. Easy enough.

In the new version, it now takes a Selection String. These are a new tool in TextMate 2 for describing selections. Here's the formal grammar for a Selection String:

selection    = «range» ('&' «range»)*
range        = «pos» | «normal_range» | «column_range»
pos          = «line» (':' «column»)?
normal_range = «pos» '-' «pos»
column_range = «pos» 'x' «pos»
line         = [1-9][0-9]*
column       = [1-9][0-9]*

OK, geeky, but what does it really mean? Let's look at some examples.

If I save the above grammar to a selection_string_syntax.txt file, I can open it with the following command:

mate -l 3 selection_string_syntax.txt

That would drop my caret (shown as ‸) at the beginning of the third line:

‸pos          = «line» (':' «column»)?

If I prefer though, I can control where it is in the line:

mate -l 3:16 selection_string_syntax.txt

That would place my caret here:

pos          = ‸«line» (':' «column»)?

Of course, we can also make a selection:

mate -l 3:32-3:38 selection_string_syntax.txt

That selects (shown between ‸ marks):

pos          = «line» (':' «‸column‸»)?

But wait, is this TextMate 2 or what? We have Multiple Carets now, dang it! How do we use more than one at once? Like this:

mate -l '3&6' selection_string_syntax.txt

That places two carets:

selection    = «range» ('&' «range»)*
range        = «pos» | «normal_range» | «column_range»
‸pos          = «line» (':' «column»)?
normal_range = «pos» '-' «pos»
column_range = «pos» 'x' «pos»
‸line         = [1-9][0-9]*
column       = [1-9][0-9]*

You can also make column selections:

mate -l '4:7x5:13' selection_string_syntax.txt

That gives us:

normal‸_range‸ = «pos» '-' «pos»
column‸_range‸ = «pos» 'x' «pos»

Or you can make several unlinked selections using all of the above features:

mate -l '2:18-2:21&3:1-3:4&4:18x5:21&4:30x5:33' selection_string_syntax.txt

Which selects all occurrences of pos for replacement:

selection    = «range» ('&' «range»)*
range        = «‸pos‸» | «normal_range» | «column_range»
‸pos‸          = «line» (':' «column»)?
normal_range = «‸pos‸» '-' «‸pos‸»
column_range = «‸pos‸» 'x' «‸pos‸»
line         = [1-9][0-9]*
column       = [1-9][0-9]*

You get the idea.

The best news about these new Selection Strings is that they aren't just for mate. You can also use them in the Go to Line (⌘L) and Go to File (⌘T) dialogs. For that latter, you just tack a colon (:) onto the end of the name matching string then follow it up with a Selection String.

This means that you could respond to a warning message like the following:

main.cc:32: warning: no return statement.

by selecting main.cc:32, copying that to the Find clipboard with ⌘E, opening TextMate 2, calling up the Go to File dialog with (⌘T), and pushing ↩ to go straight there. As this shows, Go to File honors the Find clipboard when it matches this format, just to make things like this easier.

Remote mate

In the past, TextMate has suffered with editing files on a server, but that's all changed now. If you regularly find yourself SSHed into a remote box and wanting to edit a file using TextMate on your own box, your ship has come in.

TextMate 2 now ships with an rmate (Ruby) script that you can drop onto servers. When you trigger rmate on a remote box, it will connect back to your box, allow you to edit, and update the file on the server with the changes.

Let me show you how to get rmate installed on a server you want edit from remotely.

Installing rmate

First, we need to copy rmate up to your server. You can find a link to the script in the Preferences… dialog of the TextMate menu, under the Terminal pane. Click that link to open the script, then finish the install with these steps:

1. Open a Terminal and type scp followed by a space
2. Drag the rmate icon out of the window title bar and drop it into your Terminal to fill in the path to the script
3. Add another space and then the server you wish to install the script on followed by a colon (:) and the path to install the script into

Your final command should look something like:

scp /Applications/TextMate.app/Contents/Frameworks/Preferences.framework/Versions/A/Resources/rmate example.com:/usr/local/bin

If you don't have SSH setup to automatically log you into the server, you may also need to provide the proper authentication options. If your user doesn't have permission to copy directly into a the directory you want to install into, you may need to upload the script to your user's home directory, SSH into the remote, and move it into place using sudo. Alternately, you could place it in ~/bin and ensure that directory is in your path.

Back on your own machine, you need to make sure TextMate 2 is ready for the incoming connections. Be sure Accept rmate connections is checked in the Terminal pane of Preferences… in the TextMate menu. You can leave "Access for" on "local clients" though, because I'll show you a secure trick for bridging the two computers.

The Magic of SSH Tunnels

With the install out of the way, you should be ready to use rmate.

To do it's job, rmate needs a connection back to your computer so that it can talk to TextMate 2. There are multiple ways you can accomplish this, but probably the best way is to use a reverse SSH tunnel. With the proper setup, you can forward the port rmate likes back to your local machine where TextMate 2 can answer the call-to-duty.

The easiest way to do this is to connect to your server using a command like:

ssh -R 52698:127.0.0.1:52698 example.com

The -R option sets up a reverse tunnel. The first 52698 names a port on the remote. It will be connected to 127.0.0.1:52698 or the same port on the connecting box. That port number is the default for TextMate 2 and rmate, so you should now be able to edit away.

To test things out, just try a command like:

rmate test_file.txt

That should contact TextMate 2 on your local box. Note that TextMate 2 does need to be running for this to work.

Type some content using any TextMate editing features you just can't live without and save the file. Then check it on your server with:

cat test_file.txt

You should see the content you typed on the server. Magic!

If you try to edit a file you don't have permission to change on the server, rmate will refuse the edit and warn you:

$ rmate /etc/crontab 
File /etc/crontab is not writable! Use -f/--force to open anyway.

You can either use the -f option to force the open in read-only mode or use sudo to get the needed permissions. Remember that rmate is a Ruby script, so RVM users will probably need to use rvmsudo to keep the same Ruby selected:

rvmsudo rmate /etc/crontab

After you verify that things are working, feel free to update your SSH setting to automatically setup the tunnel without you needing to supply the -R arguments all the time.

For a single server just add an entry like the following to your ~/.ssh/config:

Host example.com
RemoteForward 52698 127.0.0.1:52698

If you want to make those settings the default for all of your servers, use the wildcard host:

Host *
RemoteForward 52698 127.0.0.1:52698

With settings like those in place, a bare ssh command (without -R) should still establish the tunnel for you and allow you to use rmate.

Port Forwarding

SSH tunneling is probably the lowest configuration option for using rmate. It's also the safest since the computers chat over an encrypted connection. Go that way if you can.

However, if you can't, you do have other options. One reason you might need these is if you use multiple machines to connect to the same account on one remote. They wouldn't all be able to use the same port.

Of course, you can specify different ports when you setup TextMate 2 and/or your SSH tunnel. rmate also supports --host and --port options, so you can use those to customize the connection.

One thing you may desire in complex connection scenarios is for rmate to just connect back to where the connection came from. You can have it determine the IP address the SSH connection came from using --host auto.

You will probably need to setup port forwarding of the desired port in your router's settings to use a connection like this.

The real trick with these connections though is that it's really the client that knows how things should best be handled. Using another feature of SSH, we can have the client set some variables to the proper details and forward those settings to the remote so rmate can honor them.

A server whitelists the variables it will accept from connecting clients, so you'll need to edit /etc/ssh/sshd_config. It probably already have these lines in it:

# Allow client to pass locale environment variables
AcceptEnv LANG LC_*

You need to add allowances for RMATE_HOST and RMATE_PORT, so change that second line to read:

AcceptEnv LANG LC_* RMATE_*

You also need a similar entry in your local ~/.ssh/config:

Host example.com
SendEnv RMATE_*

Again, you can put that setting under the host wildcard if you prefer.

Then you can add lines like the following to your local ~/.bashrc:

export RMATE_HOST=auto
export RMATE_PORT=12345

Those settings would be forwarded up to the server when you connect and rmate would use them to connect back to your computer for edits.

Either way, it's a little work to get rmate setup, but it sure expands TextMate 2 reach once you do. Welcome to remote editing with TextMate.

In this article will discuss:

• Using multiple carets with the mouse
• Changes to column selection
• Using multiple carets with Find
• Using multiple carets with Copy and Paste

Using the Mouse

Let's look at an example. Pretend we're building some sort of IO filter. It allows you to wrap a file or some other stream and read data from it, but that data is modified on the way in. In Ruby, you might have some code like:

class IOFilter
  # ...

  def gets(*args)
    filter(@io.gets(*args))
  rescue IOError => error
    handle_error(error)
  end

  def read(*args)
    filter(@io.read(*args))
  rescue IOError => error
    handle_error(error)
  end

  # ...
end

Rescuing IOError covers some of the things that could go wrong. For example, if the @io object we're wrapping was opened for writing but not reading, an IOError will be tossed. There are other errors that can be raised for read operations though. For example, a socket might raise an EOFError when the input is exhausted. Let's say we received a bug report and need to add some handling for that error as well. Assuming our handle_error() method is up to the task, we just need to add the new error in two places. Here's where we would like to have our carets (shown with ‸):

class IOFilter
  # ...

  def gets(*args)
    filter(@io.gets(*args))
  rescue IOError‸ => error
    handle_error(error)
  end

  def read(*args)
    filter(@io.read(*args))
  rescue IOError‸ => error
    handle_error(error)
  end

  # ...
end

TextMate 2 makes it trivial to do just that. Click in either location to move the caret there, then ⌘-click in the second location to add another caret. You are now editing in both locations, so all we have to do is type , EOFError to add it to both lines.

We asked for the feature and we got it!

Is it Really About the Mouse?

If you have read this far and you are like me, you should have one burning question: what made Allan give in? You might like answer: he realized that this feature wasn't just about the mouse. That means we got more than we bargained for with our request.

Some features in TextMate 2 have been rethought in terms of multiple carets and new features have been added with multiple carets in mind. These combine to create a powerful system which gives you many different ways to edit in multiple places at once, without needing to learn a ton of new tricks.

Jagged Columns

If you used TextMate 1 for any amount time, odds are good that you saw column selection in action. It was my weapon of choice when I wanted to show off some quick editing tricks.

TextMate 2 still has column selection, of course. It's really just a use of multiple carets now though and that dramatically increases the ways in which we can use it.

For example, let's say we have some lines of data that vary in length:

one
two
three
four
five
six
seven
eight
nine
ten

Now I can put my cursor at the front on all of those lines the same way I did in TextMate 1: move the caret before the o in one (⌘↑ if it's at the beginning of your document), press ⇧⌥↓ to drag a selection down in front of the t in ten (this is a column movement command), and tap ⌥ to switch to column selection mode.

In TextMate 1, that gave you a special case selection that would always stay lined up vertically. But it TextMate 2, you can just think of it as ten different carets. That means we now have this:

‸one
‸two
‸three
‸four
‸five
‸six
‸seven
‸eight
‸nine
‸ten

But those carets may not stay in a perfect line if our editing actions require otherwise. To show that, let's move to the end of those lines (⌘→):

one‸
two‸
three‸
four‸
five‸
six‸
seven‸
eight‸
nine‸
ten‸

It's worth noting that getting a caret at the end of a group of selected lines was a separate feature in TextMate 1 called Edit Each Line in Selection (⌥⌘A). I loved that feature, but didn't need it often enough to remember the keyboard shortcut for it. I always went hunting through the menu. However, now that it's just another use of multiple carets and I can get to it using commands I am intimately familiar with, like column selection and the movement keys, I think it will be a lot more natural to pick up. For this reason, Edit Each Line in Selection was removed from TextMate 2.

Again, you can use most normal editing commands with multiple carets. Insert some text, delete text, move around, etc. If you use variable width commands like Select Word (⌃W), Select Enclosing Typing Pairs (⇧⌘B), Select Current Scope (⌃⌥B), any movement keys, forward delete (⌦) or backward delete (⌫), Find Next (⌘G), or even something like Toggle Case of Character (⌃G), your carets may end up in different positions on different lines. That's why these commands can be so powerful when combined with multiple carets since they allow you to edit in terms of concepts like "words" or "scopes" which could mean something a little different for each caret.

An Aside, Literally

TextMate 1, had a special editing mode called Freehand Editing (⌥⌘E). It allowed you to place the caret beyond the boundaries of the data. If you edited in these margins, the gaps were filled in with spaces.

In TextMate 2, you don't really need to activate this mode due to some simple enhancements to caret placement. Column selection is immune to data boundaries, for example.

Thus, if I write the following Ruby method call, notice I forgot the commas after the arguments, and have my caret positioned as shown:

method( arg_one
        arg_forty_two‸
        arg_three )

the fastest fix is ⇧↑ to create a selection, ⌥ to switch it into column mode, and type a , to enter it on both lines. This works because the top caret is in Freehand Mode. (Technically, this exact example also works in TextMate 1, but in TextMate 2 you can move the carets with the top one staying in Freehand Mode as needed.)

In TextMate 2, you can also make this correction using the mouse. An ⌥-click allows you to place a caret beyond data boundaries (in Freehand Mode). That works for multiple carets too, so you could just make an ⌥⌘-click above your first caret in the example above and type the ,.

Finding More Carets

There's another way to get multiple carets without ever leaving the keyboard and that's the new Find All feature.

If you need to do some tricky replacement, you can always bring up the Find dialog, craft a regular expression, and turn it loose on your data. That works, but it may require a few tries and a little use of Undo to get exactly what you need.

Find All is the other option. It's basically a live edit Find and Replace feature using the normal TextMate 2 editing tools. Oh, and you can totally skip the dialog if you like.

Ready for an example? What if we had some code doing logging in various places?

logger.info "Starting work..."
#...
if very_bad_stuff?
  logger.error "Uh guys, we should NEVER be here!"
end
#...
logger.debug "The current_user is:  #{current_user.id}."
#...
logger.info "Done."

Now let's say there is a decision to start using a different logger API. It doesn't have as rich of an interface, replacing methods like info(), error(), and debug() with just log(), but it is going to aggregate the messages from all of your servers onto a centralized box. It was decided that the tradeoff is worth it.

You can change the needed method calls with these steps. First, just select any occurrence of logger and push ⌘E to put it on the Find clipboard. Then trigger Find All (in Selection) with ⌥⌘F (it automatically works on the whole document if the current selection matches the clipboard). That should highlight all logger references in the document. Those selections are just multiple carets with some preselected content. Tap → twice to move over to the method calls and you should see this:

logger.‸info "Starting work..."
#...
if very_bad_stuff?
  logger.‸error "Uh guys, we should NEVER be here!"
end
#...
logger.‸debug "The current_user is:  #{current_user.id}."
#...
logger.‸info "Done."

From here the replacement is trivial. Select the methods with ⌃W and type log to replace them. Job done:

logger.log "Starting work..."
#...
if very_bad_stuff?
  logger.log "Uh guys, we should NEVER be here!"
end
#...
logger.log "The current_user is:  #{current_user.id}."
#...
logger.log "Done."

As I showed, Find All will match whatever is inside of a selection when you have one. If you don't though, it defaults to the entire document.

Copy and Paste Meets Multiple Carets

One question that's bound to arise is, can I Copy and Paste with multiple carets? Sure you can.

Let's go back to our list of numbers as an example. We will start with a many-to-many example. Say we want to break this list into two columns:

one
two
three
four
five
six
seven
eight
nine
ten

Do some ⌘-clicking to get a caret on every other line:

one
‸two
three
‸four
five
‸six
seven
‸eight
nine
‸ten

With that done, press ⌃W to grab the words, ⌘X for Cut, and ⌫ to remove the extra lines. That leaves us with:

one‸
three‸
five‸
seven‸
nine‸

If we don't need even columns, we can just add a space and Paste (⌘V) right now.

For even columns, just ⌥-click a space or two after the three or seven. Then use that caret to line up four ⌥⌘-clicks. You should end up with:

one    ‸
three  ‸
five   ‸
seven  ‸
nine   ‸

A simple Paste (⌘V) finishes the job:

one    two
three  four
five   six
seven  eight
nine   ten

The one-to-many case works as well, by just repeating the content. Let's say we have some metric data:

12
 5
27
 2
--
46 "bugs"

but perhaps your pointy haired boss would prefer to see the word bugs on every line. Just double-click the word bugs and Copy (⌘C) it. Press ↑ twice to end up behind the 2, then ⇧↑ three times to drag a selection behind the numbers, and ⌥ to switch into column mode. Type a space and Paste (⌘V). This pastes four copies of the clipboard contents, leaving you with:

12 bugs‸
 5 bugs‸
27 bugs‸
 2 bugs‸
--
46 "bugs"

Notice that we get to keep our multiple carets with each one placed after the pasted text. That's good, because I forgot to grab the quotes. We can add them with ⌃W to select the words and typing a single quote.

Finally, the many-to-one case collapses data as you would expect. So if we had Ruby data like:

name = { first: "James",
         middle: "Edward",
         last: "Gray",
         # leave the following out of dumb web forms
         suffix: "II" }

and we want to collapse that into one string, we could select the first colon, add it to the Find clipboard with ⌘E, switch the selection to the entire hash with ⇧⌘B, Find All with ⌥⌘F, then press → three times to move to the names. Now we have:

name = { first: "‸James",
         middle: "‸Edward",
         last: "‸Gray",
         # leave the following out of dumb web forms
         suffix: "‸II" }

From there select the names with ⌃W, Copy (⌘C) them, switch the selection back to the hash with ⇧⌘B, and replace it with the names using ⌘V. That gives us:

name = James‸Edward‸Gray‸II‸

We can finish off the string by typing a space to add it after each word, pressing ⌘→ to merge down to one caret at the end of the line, removing the extra space with ⌫, selecting the names by pushing ⇧⌥← four times, and typing a quote to enclose the string. That leaves:

name = "James Edward Gray II"

As you can see, all of these multiple caret features combine to create a powerful suite of editing tools. Thanks Allan, for knowing what we wanted more than we did.

(This bundle will only work with the 2.0 alpha.)

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.

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.

Also listed are a variety of theme bundles, you can filter list by clicking 'Themes' in the top bar. The Themes bundle is installed by default and includes a collection of themes from 1.x.

For the duration of the alpha we have kept the support files separated so both versions can be run without affecting the other. This means you will have to manually move over your personal bundles and any bundles not available in the installer.

Installing a Bundle

You can install a bundle by placing it in this directory:

~/Library/Application Support/Avian/Pristine Copy/Bundles/

When placed here TextMate will write any changes made in the bundle editor to a 'delta' bundle allowing you to update this copy without removing your customizations.

If this is your own bundle or you want to submit changes back to the bundle you should instead use:

~/Library/Application Support/Avian/Bundles/

Note:

• The ~ character in these paths refers to your home directory (/Users/«yourname»/).
• The Library folder under Lion is hidden by default, you can access it from the Go menu in Finder while holding down option.
• The directories under Application Support may not exist on your system, should they not you should create them.

Converting a Theme

If you have a theme from 1.x you will need to move it into a bundle before using it with 2.0.

1. Select Edit Bundles… from the Bundles menu and create a new bundle with ⌘N
2. Edit the bundle info in the drawer and add a description of the theme in the main text area.

3. Save your changes with ⌘S and then in Finder go to:

   ~/Library/Application Support/Avian/Bundles/
   

   Right-click on the bundle and choose Show Package Contents.

4. Add a new folder named Themes and put the theme(s) inside it.
5. TextMate will automatically see your changes and the theme will be available under View → Theme.

Other Bundle Notes

• Duplicate bundles installed at a higher level now completely eclipse the other bundle rather than being merged as in 1.x.
• If you have a problem with a bundle please submit an issue at the appropriate bundle under the textmate user on Github.
• If you would like to submit a change to a bundle most are available under the avian user on Github. You can fork the bundle and then send us a pull request.

Around the Web

• Ernie Miller give a good overview of how to use rmate to edit files on a remote server.
• David Lanham shows a detailed shot of the new icon he designed for us. Update: David has posted a comment about the process of coming up with the icon.