TextMate News

Anything vaguely related to TextMate and macOS.

TextMate’s Many Key Shortcuts

I have previously posted about cheat sheets and recently saw a new cheat sheet plus this nice idea of making a desktop background with TextMate shortcuts, so I decided to write a post with a few tips related to finding TextMate functionality, conventions, and the modifier glyphs.

Common Misunderstandings

Two common problems users run into related to key bindings are:

  1. Return () is not enter () — Some actions will show as the glyph, for example the button used in the commit window (for Subversion etc.).

    The enter key is part of the numeric keypad on external keyboards. Laptop keyboards generally have a dedicated key for enter, though it can also be reached by using fn-↩.

  2. The menu glyph is not the key — When a glyph is shown in the menu then you need to press the keys required to generate that glyph. For example if the menu shows ⌃< (control less-than) then on a US keyboard layout, where you would normally press ⇧, (shift comma) to insert a less-than character, the full key sequence becomes ⌃⇧, (control shift comma).

    This also means that a key equivalent like ⌘[ requires you to actually press ⌥⌘8 on many european keyboards, which conflicts with the key to turn Zoom on/off (Universal Access). You can change the key used for zoom in System Preferences → Keyboard & Mouse → Keyboard Shortcuts (or you can use ⌥⇧⇥ to Shift Left in TextMate)

Finding Actions

A feature to be aware of when perusing the menus is that menu items can hide behind other items. Try for example to open TextMate’s File menu (in sticky mode) and press the or modifier key. You will see that a few items change their label. The item hidden beneath is a slight variation of the primary item, for example Close All Tabs is hidden behind Close Tab.

This feature is sometimes criticized because it makes things not discoverable by only looking, and TextMate makes it worse by not limiting itself to only hiding items behind a press of the modifier key. But with an average of almost a dozen items in each menu (excluding the Bundles menu) I feel the added value in less items per menu makes up for lost usability in not having the items plainly visible — that said, some items presently hidden might become primary, and some primary items might become hidden. The goal is of course to hide what most users would anyway not use.

The Bundles menu is where all the functionality of TextMate is buried. Generally each language / task has its own bundle, but there are several bundles which offer general functionality, and in addition to looking at the bundles for the languages you use, I recommend also checking out the following bundles:

  • Diff — This is not bbdiff or FileMerge (which is an oft requested feature) but rather a front-end to the diff shell command with some interesting document sources, for example compare your document with the last saved version, or see the changes between what’s on the clipboard, and the current selection.

    The latter action is useful if you somehow ended up with two versions of the same function and want to cut one of them. To ensure they are actually identical, just copy one to the clipboard, select the other, and now invoke Diff → Selection With Clipboard.

  • Hyperlink Helper (new) — I plan to write a separate post about this bundle, as its design is also of interest: it has commands to generate a link from the current word/selection, for example by looking it up on Google, Wikipedia, etc. or using the current URL from the clipboard. The interesting thing is that these commands use a template for the actual markup, so the same commands work in BBCode, DokuWiki, HTML, Markdown, Mediawiki, MoinMoin, reStructuredText, Textile, and TWiki. Adding templates for new markup languages is easy and can be done without editing any of the commands in the bundle (which is the neat thing about this design).

  • Math — If you ever need to do calculations while typing in TextMate, this is a very useful bundle. I did a screencast about the Math bundle.

  • Source — Functions related to working with source code, this includes commenting/un-commenting text, toggling quotation style for strings (something I never thought I’d use, but actually use roughly on a daily basis), aligning code, and more.

  • SQL — Although this bundle is for a language, I find it very useful to be able to execute SQL queries from scratch documents. Check out the Help file in this bundle for setup.

    Having snippets (with tab triggers) for typical queries makes TextMate an even more attractive query runner.

  • Subversion — Not everybody knows that TextMate actually has very great subversion support (yes, you do not get to see the status of a file in the project drawer, but it basically does everything else and more :) ).

  • Text — This is analogous to the Source bundle, but more geared toward prose and text in general. For source code editing though there are still some very useful actions, such as duplicating the current line / selection, sorting lines, deleting current line, inserting the current date, etc. This bundle also has a semi-oft requested Word Count command.

  • TextMate — While this bundle is not directly for working with text, it has three very useful actions:

    1. Paste Line / Selection Online… — This will paste a syntax highlighted version of your text to pastie and allows you to send the link to Adium, iChat, Colloquy, the clipboard, or similar. If you are behind a proxy then Mac OS X Hints recently had a tip about using Paste Online behind a proxy.

    2. Create HTML From Document / Selection — This will generate HTML from the current document which you can use to get syntax highlight in Keynote or you can actually use Window → Show Web Preview to render it, and then hit ⌘P to print it, to make up for TextMate’s lack of color printing. If you do this a lot, I recommend going to the bundle editor, locating this item and change its output from New Window to Show as HTML, that way, it will open directly as rendered HTML (from where you can print).

    3. Install “Edit in TextMate”… — This will install an input manager that adds an “Edit in TextMate…” menu item to all Cocoa applications which you can invoke when editing text in a NSTextView or editable WebView (as is used in Mail).

  • TODO — If you annotate your source with useful tags such as TODO and FIXME then you can use the Show TODO List from this bundle to show a nice list of things you need to-do.

  • Xcode — If you work with Objective-C, don’t miss this crucial bundle for creating, building and running your Xcode projects, adding files to them, or quickly switch to the current project in Xcode.

So that was ten bundles you should familiarize yourself with in addition to the bundles for the actual language you work with. For something like Rails that might be both the CSS, HTML, JavaScript, Ruby, and Rails bundles, and maybe also the Prototype bundle, etc.

Remembering all the key equivalents and tab triggers is hard, and TextMate has a nice feature to help you here. In the bundles menu is a Select Bundle Item… action with key equivalent ⌃⌘T. If you only want to learn one key equivalent, be sure to learn that one!

Basically it opens a window very similar to the Go to File… window, where you can enter a search string to quickly jump to a particular file.

The Select Bundle Item… window works in a similar way. It initially shows you all the bundle items available from the current scope, but allows you to search these, for example entering “comment” will show several functions related to commenting, e.g. Comment Line, Insert Comment Banner, Insert Block Comment, Insert Comment Header, etc.

By default only items reachable from the current scope are shown, but if you type the search string in UPPERCASE then it will search all scopes.

The window can also search your bundle items based on the key sequence you press. Click the magnifying glass and change the search criterion from “Item title” to “Key equivalent”, now pressing a key sequence will show all the items (reachable from the current scope) that matches this key sequence.

Conventions

TextMate uses a lot of different modifiers and it might help remember them by understanding the conventions behind choosing modifiers for a key equivalent.

Many standard actions are offered by different bundles, for example both HTML, LaTeX, Markdown, and similar have an action for “making the selection bold” (by inserting appropriate markup) which is reached by pressing ⌘B. The list of “standard” action is given in the assorted bundles section of the manual and augmented by the bundles style guide (scroll down to Key Equivalents).

Keyboard Modifier Glyphs

Finally let me talk about the modifier glyphs in general.

The canonical ordering of the modifier glyphs is ⌃⌥⇧⌘, i.e. from lightest to heaviest glyph.

If you wonder how to easily type these glyphs then see my post about multi-stroke key bindings.

If you need a fixed width font to handle these glyphs (and many more) then I recommend the DejaVu Sans Mono font (based on Bitstream Vera Sans Mono). Mail has a tendency to switch font when rendering a glyph that is not available in the current one, so if you like to have your messages displayed using a monospace font and receive messages with fancy glyphs, then DeJaVu Sans Mono is the best choice.

categories General

19 Comments

great post ;-)

That helped a lot. TextMate is way more powerful than I will ever know!

I didn’t know that you could seach all the bundle items, rather than based on scope, when you type in all UPPERCASE. Good to know.

07 May 2007

by Gerry

I’ve used the search bundle feature before and find it very useful but I sometimes try to search for items that aren’t in any bundles (ie, lowercase text) because I can’t remember the hotkey. It would be great if all the available commands in textmate could also be searched and executed that way. If you searched in UPPERCASE maybe it would search all available commands (even ones that are grayed out).

It would be really great if TextMate would work a bit more like Emacs with regard to shortcuts. There should be a way to find out what a particular shortcut does (as “F1 k” does in Emacs). Currently there is no way to find that out without trying and see what happens.

There should also be a more unified way of changing shortcuts – right now there are no less than three kinds of different shortcuts with three ways to change them: Menu equivalents (changeable only through the system keyboard preference pane), Cocoa text system shortcuts (changeable by editing a cryptic plist) and shortcuts from bundles, editable with the bundle editor.

Last but not least: Shortcuts could be much more easily remembered if they would be grouped by using sequences of keys with one modifier instead of combinations of up to three (or even four!) modifiers with one key. TextMate already has a bit of this by the way it treats bundle items with the same shortcut: when the shortcut is pressed, it lists all options in a menu and allows to select one with the keys 1 to 9. This could be extended by allowing bundle items to have a “secondary key” which comes into play when more than one item has the same shortcut: TextMate could then display a menu with choices, displaying the secondary keys instead of numbers.

TextMate shortcuts really drive me nuts. Compared with Emacs it’s a mess with loads of totally arbitrary key combinations which are also often totally different for very similar functions. It would be much, much better to have (for example) Control-C used for all functions related to converting and have it display a menu with options where “R” does ROT13 conversion, “L” converts to lower case, “T” to title case and so on. This way you would have to learn only a smaller set of (grouped) shortcuts and then could see what is on offer in this group and just additionally press the key for the wanted function which is displayed in a menu.

Anyway, this article was nice and useful, but TextMate just has to change its way to work with shortcuts. It’s the one most pressing bottleneck for adding further functionality to it. You just can’t remember hundreds of arbitrary combinations of Control, Shift, Option and Command with a key and when more bundles (or more powerful bundles) get added this will grow worse and worse. With sequences (simple shortcuts for groups of functions with secondary keys for selecting one) there’s room for more functionality and you still get easier usage.

And, uh, sorry for the long comment…

08 May 2007

by Dan Kelley

Joh raises some excellent points. I love TM, but I find the key chords quite challenging to remember. Some of them are also quite difficult to execute. I like the chord-sequence idea quite a lot, both because it would permit categorization of commands and because it ease typing.

I’d also like to see a palette system of some sort, for frequently-used commands. The idea here is to provide a mouse-driven interface (to just a few commands) that is easier to use than the menu tree that hangs from the gear icon. I find navigating through the tree to be very difficult and error prone, especially when I’m using the mousepad on my laptop. (Of course this is not TM-specific.)

I realize that changing key chords might be difficult, since people get used to things. For example, I’d flip out if control-A did anything but the “right” [Emacs, bash, …] thing. Still, I’d be very open to new bindings for some of the more detailed things. Heck, I don’t know the bindings anyway … when I’m in markdown mode and want to do a preview, I just start holding down a whack of keys while also pressing P and hope for the best.

All of my comment must be tempered with an admission of my idiocy: I don’t know what some of the symbols for keys actually are! The icon for “option” looks like it should mean “shift”, for example … somehow it calls to my mind the action of a manual typewriter. Those who know about Bayesian statistics will call this paragraph the “prior information” :-)

joh: Thanks for the feedback. As for finding out what a key equivalent does, I think you missed the following from the post:

The window can also search your bundle items based on the key sequence you press. Click the magnifying glass and change the search criterion from “Item title” to “Key equivalent”

As for central key bindings, a system for that will appear in 2.0.

With 2.0 a lot of functionality will also be remapped to new keys. The present situation stems from evolutionary adding functionality, and the upgrade makes it possible to take a step back and rethink things.

Presently you can use letters when TM shows a menu (for when multiple items share the same key). For example ⌃⇧A + C is commit, ⌃⇧A + S is status, ⌃⇧A + D is Diff… (with the ability to arrow down to select which of the diff options you want), etc.

Dan: Palettes is not an uncommon request, and I am introducing a new system in 2.0 which might be used for palettes, although I might do a tool bar before a palette, but basically with TextMate’s many modes (and context sensitive behavior) you need a system for grouping all the mode-specific Run commands into one item, and maybe fallback on the Preview item, should the current mode not offer a run command, etc.

That’s what 2.0 will introduce, and this should also greatly simplify the central key bindings joh requests (you really do not want to just show a list with 2,044 actions and corresponding key ;) ).

08 May 2007

by Dan Kelley

Feel free to charge for the 2.x upgrade. I’m looking forward to it eagerly!

09 May 2007

by grant

I find that I use more shortcuts in TextMate than I ever did in Emacs, especially once I discovered ⌃⌘T. I really missed C-h C-k until Allan mentioned the key equivalent magnifying glass in a mailing list post.

I noticed today when using ⌃⌘T to look for a diff command that none of the Diff bundle’s commands has ‘diff’ in its title. It makes sense for the bundle menu, but not so much when searching.

Speaking of diff, the command that I always want for Subversion is Diff with Newest. Why is that the second option? The CVS bundle has it first. Do people really use Diff Revisions that often?

grant: It is a system menu, and thus we are victims of system rules.

The system will, when you type a sequence of letters, sort all the items in the menu (alphabetically), then it will find (in this sorted list) the first item which is not (lexicographically) lower than what you typed.

It will select that item in the original menu.

This means that even if we did place ‘Diff With Newest (HEAD)’ as the first item starting with ‘D’, the system would still pick ‘Diff Revision…’.

14 May 2007

by Joseph Grace

Dear Allan: To reiterate Joh’s point, I just tried the KeyEquivalent trick in the bundle window. (Here, OSX) it does not work for general keys (e.g., undo, paste, or even ^-apple-T (itself)), but only seems to work for bundle keys. Such an item for all key equivalents would address Joh’s general point. I concur that is a seriously needed feature.

If/when you add that feature, please add a column to the command viewer (for both types of searching) for the TextMate command symbol that shows up in macros as well. I have some need of that. For instance, I’d like to search for Gear Menu. On my OSX MacBook Pro, for some reason, the key ^-escape (Gear Menu) does not register at all with TextMate. I do not know why. I can not remap (Gear Menu) because it doesn’t exist in the menu system that I can find. I’d like to remap it manually to another key.

Which segues to another request. Please make the macros editable so that steps can be deleted, and steps can be added (again, the ever elusive Gear Menu comes to mind).

Which brings up another request. With all these wonderful macros running around, please add outliner organization to the Bundle Editor to enable some organization of items into groups/categories, etc..

I know that’s a lot, but it’s all about the keystrokes, so please make the keystrokes first class citizens. That is, please make them easily searched, reverse engineered, macroized, edited (macros), and categorizable for organization and sharing.

What a great editor. I look forward to 2.0!-)

Joseph: [From Troubleshooting → Key Bindings] If the key in question is ⌃⎋ (to open the bundle menu), then the problem is caused by Apple’s Remote Desktop application, you can disable ARD in System Preferences → Sharing.

As for how to remap it: OakBundleItemsPopUpMenuKeyEquivalent

I am aware that the current key binding system is fragmented and thus confusing. This comes from drawing on the OS as much as possible, which is necessary for several reasons. Even if I want, I can’t write a full replacement for what the OS does with “events”, i.e. to have better control of things, but I am doing what I can to make things appear more harmonized in the future — at the same time I also need to actually give up some of my currently “replaced” event handling code, to enable system features that I just can’t recreate.

21 May 2007

by Joseph Grace

Allan, once again: Thank you!

Bingo on the ARD diagnosis. Now the keystroke shows up in KeyCodes. (It was such a longstanding problem, I was concerned it was something hardware related. ARD! Argh!)

Bingo on the OakBundleItemsPopUpMenuKeyEquivalent suggestion. I was able to find an errant setting in my com.macromates.textmate.plist. Now my GearMenu works with ^Escape (as desired).

Well, I’m really glad you’re on the job. Thank you for sharing the caveat(s) about non-ideal keyboard control. I think just making live keystroke mappings visible (i.e., reverse map keystroke to command(s)) would be a huge step in ShowBundles, as well as Macros). For example, perhaps add a column listing any mapped keystroke(s) in the ShowBundles listing next to each entry (a la QuickSilver in its Preferences->Triggers listing). Any additions to reverse mapping basics would be icing on the cake. IMO.

Thanks so much,

= Joe =

Does the stats/word count command understand it should not count LaTeX syntax?

Does the stats/word count command understand it should not count LaTeX syntax

I accidentally made my project drawer to sort items by name DESC. How to reset sorting back to name ASC?

I used to use Command Left (arrow) to move the beginning of a line and Command Right to move to the end of a line, but since I re-installed TextMate (on Snow Leopard) it just beeps at me! It seems to be textmate-specific, any ideas why?

JP: Download the bundle attached to this ticket for a workaround.

hey, please check the desktop wallpaper link. its not working for me.