BasicsTest

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 seriously wants to use TextMate.

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

Content

  • [Understanding TextMate][]
    • [Bundles][]
      • [Commands][]
      • [Snippets][]
      • [Macros][]
      • [Languages][]
      • [Preference Items][]
      • [Templates][]
    • [Special Bundles][]
    • [Conclusion so far][]
  • [Editing Text][]
    • [Caret Movement][]
    • [Selections][]
      • [Column Selection][]
    • [Indents][]
    • [Copy/Paste][]
    • [Word Completion][]
    • [Find & Replace][]
      • [Incremental Search][]
    • [Transposing and Conversions][]
      • [Tabs and Spaces][]
      • [Formatting][]
    • [Special Edit Modes][]
  • [Running Shell Commands][]
  • [Common Bundles][]
    • [Common Bundle Shortcuts][]
    • [Text Bundle][]
    • [Source Bundle][]
    • [Diff Bundle][]
    • [Math Bundle][]
    • [Subversion Bundle][]
    • [TextMate Bundle][]
    • [TODO Bundle][]
  • [Navigation][]
    • [Bookmarks][]
    • [Text/Code Folding][]
    • [Structure][]

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

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) from the Menu or by pressing.

![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) and several Preferences you can adapt to your needs. At the bottom we has different kinds of Templates for various HTML versions.

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.

Commands

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!

See the TextMate Manual to learn more about commands.

Snippets

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

    <br />
    

    This is basically the simplest Snippet you can get. It is bound to ⌃↩ (Control-Return) in HTML Documents. Try it! It just inserts those characters.

  2. Text with Placeholders (and default values)

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

    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 (by typing meta and pressing ⇥ (Tabulator)) 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 gets you started. For more details check out the Manual.

Macros

Macro Icon Macros are recorded Keystrokes or Command invocations. They can be recorded and saved from the Automation 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.

Languages

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 <div> will have the scope of meta.tag.html and for the name “div” 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 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:

  • “smartTypingPairs” – They define pairs of characters so that the second character gets automatically inserted when you type the first character. Try it with " for example. And try it again while you have some text selected. This saves you time and lets you not forget to insert the closing character of (e.g.) a string.
  • “shellVariables” – This lets you define Shell Variables to be available for Commands in certain contexts. This is e.g. used for the “Comment Line / Selection” Command. (More on that later.)

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

Templates

Template Icon

> 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

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.


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

  • ⌃F, ⌃B Character forward/back

  • ⌃A, ⌃E Line beginning/end

  • ⌃P, ⌃N Line up/down

  • ??, ⌃V Page up2/down

  • ⌘J (Edit → Find → Jump to Selection) Center selection on screen

  • ⌃L Center line with caret on screen

  • ⇧⌘J (Navigation → Go to Middle Visible Line) Go to Middle Visible Line, moves caret

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.

Selections

  • ⌃W (Edit → Select → Word) Select current Word

  • ⇧⌘L (Edit → Select → Line) Select current Line

  • ⇧⌘B (Edit → Select → Enclosing Brackets) Select enclosing Smart Typing Pair (see [Preference Items][]). This can be Braces, Brackets, Curly Braces, "<", ">", Quotation Marks, etc.

  • ⌃⌘←→ (Text → Move Selection → Column Left/Right) Moves the current Selection character-wise

  • ⌃⌘↑↓ (Text → Move Selection → Line Up/Down) Moves the current Selection line-wise.

  • ⌥⌘A (Text → Edit Each Line in Selection) lets you insert text at the end of each line in the current selection.

  • ⌥F2 will bring up the Context Menu (like right-clicking) so you can easily correct the spelling of the current word or use conversion commands on a selection.

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.

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.

Indents

> 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.

Copy/Paste

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

  • ⌃⌘V (Edit → Paste Previous) pastes the previously copied item

    • Using this more than once will subsequently insert older items form the Paste History and make them available for the standard ‘Paste’ command as well.
      An example: Copy "1", Copy "2", Copy "3", Paste → "3", Paste Previous → "2", Paste Previous → "1", Paste → "1".
  • ⌃⌥⌘V (Edit → Paste from History) brings up a popup menu containing all things copied or cut in this editing session. Once you select an item from this list, the normal “Paste” operation will keep inserting this item until you Copy or Cut something again.

  • ⌃D Forward delete character/selection

  • ⌃K, ⌃Y Kill & Yank

    • Similar to “Cut” and “Paste”, things killed can be yanked. This uses a different buffer than standard Copy/Paste but “Cut” will overwrite this buffer, too. (This is strange OSX default behavior.)
  • ⌃⇧K (Text Bundle → Delete Line) deletes the current line

  • ⌃⇧D (Text Bundle → Duplicate Line) duplicates the current selection or line

    • With a selection, TextMate will duplicate it and insert it after the selected area leaving the duplicated text selected, so you can go on duplicating it again.
    • Without a selection TextMate will duplicate the current line and insert in below, placing the caret on the new line.

Word Completion

  • ⎋ (Edit → Completion → Next 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.

Formatting

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 [[TextMate Setup Tutorial]] already.

⌃Q (Text → Reformat Paragraph) will reflow the current paragraph according to the Wrap settings. ⌃⌥⇧U (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

  • Freehand Editing ⌥⌘E (Edit → Mode → Freehanded Editing)

    Allows the caret to move past end of line and inside tab characters.

> 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

  • Overwrite Mode ⌥⌘O (Edit → Mode → Overwrite Mode)

    This lets you type over existing text.


Running Shell Commands

  • ⌃R (Execute Line/Selection Inserting Result) will run the the current selection/line as a shell command. Use the Modifier to replace the command.

  • ⌥⌘R (Text → Filter through Command…) pops up a dialog where you can enter a shell command. That shell command will ba able to read the Text (Selection or the whole Document) as input from stdin and you have several options to show the output of the shell command. Basically this is what [Commands][] do, as discussed earlier, just ad hoc.


Common Bundles

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

  • Automation Menu
    • groups by Macros, Snippets and Commands
  • Gear Menu (⌃⎋)
    • groups by Bundles
  • Learning Tab Triggers/Keyboard Shortcuts
    • The Scope system will restrict the available shortcuts to relevant ones

Common Bundle Shortcuts

  • ⌘B Build

    • used in programming/markup languages to build/compile/convert the current Project/File
    • Java (“Build with Ant”), LaTeX (“Typeset and View”),…
  • ⌘R

    • used in programming languages to Run the current Project/File
    • AppleScript (Run), HTML/CSS (“Refresh Running Browser(s)”), Perl (“Run”), Python (“Run with PyMate”), Ruby (“Run”), Unix Shell (“Run Script”),…
  • ⌃H

    • Look up current Work/Selection in the Documentation
    • CSS (“Documentation for Property”), HTML (“Documentation for Tag”),…
  • ⌃⇧H Conversions (for Markup languages), Tidy Code

    • HTML (“HTML Tidy”), LaTeX (“Tidy”), Markdown (“Convert Document to HTML”),…
  • ⌃⇧V Validation/Syntax Check

    • CSS, HTML, Perl, PHP, Python, Ruby, XML,…
  • ⌃⇧W Wrap Selection

    • HTML (Wrap on Tag), Java (Wrap in try/catch), LaTeX (Wrap in Command), etc…
  • ⇧↩ Create a function/method body with previous word as name

    • Obj-C, Ruby,…
  • ⌃↩ Insert a “descriptive” return

    • HTML (<br/>), Markdown (hard line break), Source (Escaped newline \n),…
  • ⌘↩ Move to end of line and insert a newline

  • ⌘⌥↩ Move to end of line and insert potential end-of-line symbol (; in many sources, . in prose)

  • ⇧⌘↩ As above, but also insert a newline

  • Insert a newline and start a new “item” (e.g. line comment, bullet point, etc.)

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.

Interesting Bundle items here are:

  • “Add Line Numbers to Document / Selection”

  • “Current Date — YYYY-MM-DD (isoD)”

    • A snippet with Tab Trigger isoD, will insert e.g. 2006-04-22
  • “Join Line With Next”

    • Pressing ⌃⇧J will remove all whitespace after the last character of the current line
  • “Lorem ipsum (lorem)”

    • Inserts a paragraph of placeholder text
  • “Open Current URL”

    • When the caret is inside a URL, TextMate will open it when pressing
  • “Remove Trailing Spaces in Document / Selection”

  • “Sort Lines”

    • bound to F5

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:

  • “Comment Line / Selection” This Command is very powerful. It is adaptable via [Preference Items][] items for every language. You can define comment start/end characters, make

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.

  • “Show Keyboard Shortcuts”
    • This will output a list of all Commands, Snippets and Macros for the Bundles in use (not for built-in functionality). There is even a helper on the net that will compile your own TextMate reference card.
  • “Show Scope”
    • You learned about the ‘Scope System’ (remember the [Languages][] section?). This command shows the current Scope of the caret as a tooltip. You can use this to specify a scope for your Commands or to adapt the “Fonts & Colors” (in the Preferences) and make you own theme.
  • “Search the TextMate Mailing List”
    • Pretty Self-explaining: This will popup a window where you can enter a search term and show the results in an HTML window.
  • “Install ‘Edit in TextMate’…”
    • See the [[TextMate Setup Tutorial]]. This is an extremely useful helper to edit text in any Cocoa Applications using TextMate (or FireFox).

TODO Bundle

> The “Show TODO List” command will scan your current document (on disk) or documents in your project for lines containing certain tags (see below). It will show an ordered list of these tags and their context which can be clicked to jump to that line in that file.
— ‘Help’ Command from the TODO Bundle


Navigation

Bookmarks

Bookmarks are marked 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 always cycle through your bookmarks 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, <tag> … </tag>, 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.

Structure

> 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.

[Bundle_Editor]: http://public.serenity.de/1_bundle_editor.png class=shot

[Find_Replace]: http://public.serenity.de/2_find_replace.png class=shot


  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.