Flattr this

Last updated 2009-07-25

TextMate Basics Tutorial

Welcome to the TextMate Basics Tutorial. After having setup your TextMate, this Tutorial will show you around the basic features of TextMate. This is a must for everyone who wants to use TextMate seriously.

This Tutorial starts rather unusually with an insight of TextMates Extensibility and Bundle System and also will show off the built-in editing features. I find this “Understanding TextMate” Section is essential for every user.

Notice: Part of this Tutorial is available in Japanese at fraction.jp. 有難う Yuanying!


Understanding TextMate

When you edit a file, TextMate recognizes the file type (in most cases) and provides several specific commands to work with that file.

Let’s assume you are editing an HTML file. TextMate will recognize the following extensions as HTML: html, htm, shtml, xhtml, phtml, php, inc, tmpl, tpl1. Furthermore, if your file starts with an HTML DOCTYPE declaration it will be recognized as well.
Based on that the file is syntax-highlighted according to the ‘HTML Language Grammar’ that is defined in the ‘HTML Bundle’.

Let’s take a look what those Bundles are about, shall we?


Bundles are Containers for certain functionality, mostly Language-centered. Feel free to open the ‘Bundle Editor’ from within TextMate with ⌃⌥⌘B (Window → Show Bundle Editor).

Bundle Editor

I have selected the first Command in the ‘HTML Bundle’. Don’t be scared right off by the funny program source in the text-field to the right.
All the items that are grouped under the “HTML” headline on the left are specific things to HTML. There are Commands that will transform characters or open a window with Documentation for an HTML Tag, Drag Commands that will let you Drag’n’Drop Files (will be inserted as Links) or Images into the HTML Source, Macros and Snippets (expandable, intelligent Text Blocks). Further down there is the ‘HTML Language Grammar’ (that defines how the Syntax is highlighted and provides Semantic info for Commands), several Preferences you can adapt to your needs and different kinds of Templates for various HTML/XHTML versions.

If you select the name of the Bundle you can rearrange how TextMate structures the menu of the Bundle. This menu can be called by selecting the Bundle from Bundles → [Bundle name] or by pressing ⌃⎋ [Control-Escape] (Gear menu in status bar)Gear Icon which opens the right bundle according to the context your caret (Text cursor) is in.

Bundle Editor 2

The gear menu gives you a lot of power and control right at your fingertips.

Bundle Menu

I hope, you are still with me. Let’s take a shallow look at the different things so you get a feeling of the power you have on your hands with these Bundles.


Command Icon Commands are shell scripts; little computer programs that invoke other programs to do specific tasks. They are used to transform portions of your document, invoke Documentation, Run files (for programming languages), etc. And because they are usual shell scripts, they have all the power that Mac OSX gives us – Bash, Perl, Python, Ruby, PHP, AppleScript and all those little utilities that make up a UNIX-derivate – grep, wc, etc — You name it!

I can’t got much into detail w/o repeating everything in the manual: Learn more about commands in the official TextMate manual.


Snippet Icon Snippets are powerful and intelligent Text Blocks.

It can include code to run at the insertion time, variables (like selected text), tab stops/placeholders for missing information (which you can tab through after insertion), and perform transformations on the data which you enter in the placeholders.
The Manual

Let’s see some quick examples.

  1. Pure Text


    “Non-Breaking Space”. This is basically the simplest Snippet you can get. It is bound to ⌥⎵ [Option-Space] in HTML Documents. Try it! It just inserts those characters.

  2. Text with Placeholders (and default values)

    <meta name="${1:name}" content="${2:content}" />

    “Meta”, Type meta and press (Tabulator). This is a very basic Snippet. It will get inserted into your file almost as-is. Notice the ${1:name} and ${2:content} special sequences. Those are placeholders. When you invoke the snippet it will insert <meta name="name" content="content" /> into your file, with the name bit inside placeholder 1 selected. Now you can change that selection by overtyping it (you don’t need to) and press (Tabulator) to get to the next Placeholder, which is the value of the content attribute. Type your text, press again and you get out of the snippet and can go on editing your file. Does this sound complicated? Try it, it’s easy and you will love it instantly!

I think, this will get you started. Explore the other snippets in the Bundle to find some more examples. For more details like running shell code and using regular expression replacement within Snippets check out the Manual.


Macro Icon Macros are recorded Keystrokes or Command/Snippet invocations. They can be recorded and saved from the Bundles → Macros menu.

In the ‘HTML Bundle’ there is one Macro: “Forward Delete All Whitespace”. It executes a search with a regular expression from the current caret (Text cursor) position which selects all whitespace (Spaces, Tab-characters & New-Line-Characters) until the next non-whitespace character and deletes them. You can invoke it via ⌃⌥⌦ (Control-Option-Delete [Delete = fn-Backspace for Laptop users]).

The Manual has this section about Macros.


Language Icon Languages (Language Grammars) are complicated nested rules of Regular Expressions. We can’t even scratch the surface in this Tutorial but you should know about the existence of Scopes.

Scopes are defined by Language Grammars and are considered “Markup for your Language Syntax” – or the context. There is a strong analogy to CSS selectors. Let’s say we have an HTML file. Everywhere in this file we have a scope of text.html. An HTML Tag like <p> will have the scope of meta.tag.ny.html and for the name “p” it has entity.name.tag.html. Those scopes nest and override each other. Why am I bothering you about such details you might say? Those scopes are everywhere. They are the base of the Theming/Syntax Highlighting system. And they define where certain Commands, Snippets and Macros are available (you probably saw the ‘Scope Selector’ text-field way at the bottom of the ‘Bundle Editor’). E.g. you can set a command to only work within an HTML file by setting its scope to text.html.

The Manual says this about Language Grammars and there is the explanation about Scopes as a Blog Entry and the Manual Chapter about Scopes.

Preference Items

Preference Icon Preference Items store several, well, Preferences. Most notable are:

As always, the Manual provides a chapter on Preference Items for further reading.


Template Icon Explaining how Templates work and how they are created would be too much for this little Tutorial. To give you the basic idea:

A template consists of a (shell) command which generates the actual new file and generally the template file from which the new file will be generated.
The Manual

The most important points about templates: You can create a new file from a template. Choose e.g. File → New From Template → HTML → HTML — 4.01 Strict and you will be greeted by a new document with a basic HTML skeleton. You can edit that part via the Bundle Editor when you expand the respective template and edit the index.html entry.

Special Bundles

CAUTION: The “Text” and “Source” Bundles define the basis for most other Bundles. You should not deactivate them!

Conclusion so far

I know this must have been a rough ride until now – but you will thank me at some point for the insight you have gained about the Bundles I think. TextMate is 1000% adaptable and extensible – yes, this number is right. Without those bundles that are mostly written by Users like you and me TextMate would not have 1/10th of its power.

And now for the fun part where we will use all this power.

Harnessing the power

The most vital shortcut in TextMate is ⌃⌘T (Bundles → Select Bundle Item…). It will show any Command/Snippet/Macro available in the current scope and lets you filter the list.

If you ever wonder where a Command or Snippet was or if one exists for a given purpose, invoke the Select Bundle Item action. Click on the magnifier glass symbol and choose Key equivalent and you can even search for shortcuts!

Find Bundle Item Find Bundle Item by Key

Some examples (Input → Output):

Insider-Tip: Write in ALL CAPS to have the limitation to the current scope switched off. You can search for any item in any bundle that way.

Editing Text

(Please see the TextMate manual about the conventions used for keyboard shortcuts.)

Beside the standard navigation keys there are some handy shortcuts (most of which are working throughout Cocoa/OSX applications and are common to people coming from e.g. emacs).

Caret movement

You can also move the window w/o moving the caret. This can be achieved with ⌃⌥⌘←→↑↓ and is a handy way to just move the visible editing area.


Column Selection

Pressing the Key with a selection spanning multiple lines will switch to Column Selection mode. This let’s you edit the text in columns instead of lines which will come in handy in several places.

Column Selection

There is a nice Screencast which demonstrates this feature in conjunction with the Math Bundle and how you can work with it. The Manual has a small section about Column Selections, but please take a look at the Screencast to see what you can really do.


When using the tab key at the beginning of a line, TextMate will insert as many tabs as estimated correct for that line. If the line already has text, the caret will move to the front of this text.
If the line already has the correct indent (or above) a single tab will be inserted.
The Manual

If in ‘Soft Tabs Mode’ this will of course insert the specified number of Spaces.

To manually change the indent of a line you can use ⌘[ (Text → Shift Left) and ⌘] (Text → Shift Right); also ⌥⇥ and ⌥⇤ (where is achieved using ⇧⇥).

⇧⌘[ (Text → Shift Indent Line/Selection) will automatically indent the current line/selection.

Pasting will also automatically indent the pasted text/code. To disable this either use ⌃⌘V (Edit → Paste Without Reindent) temporarily switch it off globally in the Preferences.


In addition to the standard Copy/Cut/Paste shortcuts.

Word Completion

TextMate has a simple yet effective completion function on (escape). It will complete the current word based on matches in the current document. If there are multiple matches, you can cycle through these by pressing continuously. It is also possible to cycle backwards using ⇧⎋.
The Manual

Find & Replace

There are a lot of keyboard shortcuts for Find and Replace functionality. The Edit → Find Menu tells you about them:

Find Replace

The most notable two are: ⌘E which replaces the search string with the current selection and ⇧⌘E which replaces the replacement string with the current selection (or with nothing if nothing is selected). Using these two shortcuts and a subsequent Replace or Find shortcut you don’t even have to invoke the Find dialog at all.

Incremental Search

Another rather hidden feature is the incremental search. ⌃S or ⌃⇧S incrementally searches forward/backward as you type (the status bar will turn into an input field in that case).

Transposing and Conversions

⌃T (Text → Convert → Transpose) lets you transpose things. Without a selection both characters around the caret will be swapped. With a selection on one line, all characters within the selection will be reversed. Invoking the command on a selection spanning multiple lines will reverse the order of all the lines.

⌃G (Text → Convert → To Opposite Case) with no selection will toggle the case of the character next to the caret and advance the caret. with a selection it will toggle the case of all the characters in the selection (and leave the selection in place).

⌃U (Text → Convert → To Uppercase) will toggle the case of the current word or the current selection to upper case, ⌃⇧U (Text → Convert → To Lowercase) will do the same things for lower case.

⌃⌥U (Text → Convert → To Titlecase) will switch the case of the line or selection to title case. This is intelligent to exclude common short words and is intended to be used on a line containing a title.

Tabs and Spaces

From the Text → Convert Menu (or with a selection from the Context Menu) you can choose to convert Tabulator characters to Spaces and vice versa. The ⌥⌘I (View → Show Invisibles) Menu item can help you figure out what convention the current file uses and the Tab Menu in the Status line will let you define how TextMate will insert new Tabulator characters you type.


TextMate can help you format your text or source in several ways. The ⌥⌘W (View → Soft Wrap) and View → Wrap Column items were discussed in the Setup Tutorial already.

⌃Q (Text → Reformat Paragraph) will reflow the current paragraph according to the Wrap settings. ⌃⌥Q (Text → Unwrap Paragraph) will do the opposite and reflow the paragraph on a single line.

⌃J (Text → Reformat and Justify) will do the same as Reformat Paragraph and distribute whitespace between words so that the text is justified. This can be used for quotations, etc.

While this is mainly used for text, there are some bundles that override this shortcut to provide formatting for different things. See this Screencast about how to format comments for C-like languages.

Special Edit Modes

It is also possible to place the caret unrestricted by line endings (and tabs) by holding down ⌥ while placing the caret with the mouse.
The Manual

Running Shell Commands

Common Bundles

Triggering Commands/Snippets/etc. form Bundles can be achieved with the following methods:

Common Bundle Shortcuts

Text Bundle

The Text Bundle contains common functionality for all kinds of Text documents. This includes e.g. Markdown and HTML. Those Bundles won’t work as expected with out the Text Bundle, so don’t disable this one.

Text Bundle

Interesting Bundle items here are:

Source Bundle

The Source Bundle defines the base of all programming language bundles, so don’t disable it.

It contains several very useful command like:

Diff Bundle

The Diff Bundle contains several commands to compare files and make diffs/patches. All those functions have a common shortcut ⌃⇧⌘D and work without restriction in all kinds of files.

Math bundle

The Math Bundle provides some functionality to calculate numbers inline. Just type an equation like 3+4/5 on a new line (or select it) and press ⌃⇧C to bring up the menu containing the available Commands. Select “Evaluate Line” and it will insert the result of your expression.

Also see this Screencast that shows how to use the Math Bundle and Column selections.

Subversion Bundle

Subversion Support is provided via this Bundle. Just checkout a directory or file from a Subversion repository, open it in TextMate and you can use this Bundle. All Subversion Commands use the same shortcut ⌃⇧A.

TextMate Bundle

The TextMate Bundle provides some function to help you with TextMate in general.

TODO Bundle

The “Show TODO List” command will scan your current document or documents in your project for lines containing certain tags. You will be presented with a row of “Tabs” that are counting matches while the search is going on. Once the search finishes a list for each of the tags and their context is shown. Each entry can be clicked to jump to that line in that file.
— ‘Help’ Command from the TODO Bundle



Use Bookmarks to mark places in your document. ⌥⌘B (View → Gutter → Bookmarks) will show them in the gutter (the gray panel to the left of the editable area, containing line numbers etc.) You can create a bookmark with ⌘F2 (Navigation → Add Bookmark). This will put a star (★) in the bookmark column of the gutter for that line. You can then cycle through your bookmarks in that file with F2 (Navigation → Next Bookmark) and ⇧F2 (Navigation → Previous Bookmark).

Text/Code Folding

When working in a language which has start/end markers for blocks, like { … }, do … end, , and similar, TextMate can spot these blocks and will show up/down arrows in the gutter for the start/end marker.

When these arrows are present, it is possible to fold the block into a single line either by using the mouse and clicking on the up/down arrow, or pressing the F1 key. This will make the arrow in the gutter point to the right, and indicate that the entire block got folded by placing an ellipsis marker at the end of the line. An example where the two sub-blocks of the constructor has been folded can be seen below.
The Manual

So, F1 View → Fold Current Block and View → Toggle Foldings at Level will fold/unfold your code at the current block or a certain level. Imagine an HTML file that consists of a number of divs in the body. Just press ⌥⌘2 to fold them all and you can concentrate on other things or edit them one after the other.


For languages for which it is supported, the rightmost pop-up in the status bar shows the current “symbol” (often the function prototype or heading above the caret).
The Manual

So e.g. for Markdown or Latex files it will show the headings (indented per level) of the file and you can navigate to them by selecting them from this pop-up or form the ⇧⌘T (Navigation → Go to Symbol…) list.

  1. Yes, .php files are recognized and treated as HTML. This is because they are in fact HTML files with PHP embedded in them (when using them for WebPublishing, which would be most of the time). ↩

  2. OS X does not define a standard binding for Move-Page-Up. In emacs it was M-v but OS X has no Meta modifier key. ↩