The TextMate URL Scheme

TextMate registers a custom URL scheme on your system which allows you to open files in TextMate by asking the system to open a txmt URL.

The format is: txmt://open?«arguments» where arguments can be:

  • url — the actual file to open (i.e. a file://… URL), if you leave out this argument, the frontmost document is implied.
  • line — line number to go to (one based).
  • column — column number to go to (one based).

If you have TextMate installed, you can try it out by having it open /etc/profile.

One reason for this URL scheme is that many TextMate commands generate HTML output with links that open files in TextMate. For example the TODO bundle has a “Show TODO List” command which will scan your entire project for FIXME and TODO tags, then present the found results nicely in HTML, and allow you to click on them to go to the appropriate location. Another example is the Xcode bundle, which has a “Build” command that will show errors and warnings that correctly link to your source code.

But seeing how these commands generally run in a custom HTML view inside TextMate, it is possible to use JavaScript extensions, so a much better case for the txmt URL scheme is debugging web applications!

For Rails there is Duane Johnson’s Footnotes plug-in (included in the default Rails bundle) and for PHP, Ciarán Walsh recently added a few commands to easily allow PHP scripts to markup stack traces with proper txmt links (see PHP → Help → 3.3 TextMate Support File).

An unfortunate reality of web development is that if you work on mainstream sites, you need to test your site in Internet Explorer. If you do this using Parallels Desktop for Mac then (thanks to Ruy) you can have txmt URLs work in IE.

13 Comments

  1. 24 Apr 2007 | # Luke wrote…

    In 1.5.5 r1372 there is no section 3.3 in PHP Help.

  2. 24 Apr 2007 | # Allan Odgaard wrote…

    Luke: Sorry about that — when I wrote it, I knew I had to remember to check if this is actually in the PHP bundle included with latest cutting, which clearly it is not :)

    I plan to do a build this week, which will include the latest PHP bundle.

  3. 25 Apr 2007 | # Chris Adams wrote…

    This is very cool – I just updated my PHP error handler to generic those links similar to Ciarán's code. One thought: it would be handy if opening a file which is already open would reuse the open window rather than creating a new one; frequently I find myself wanting to use the links as a shortcut to avoid having to go into that window, hit Command-L and type in the line number.

  4. 26 Apr 2007 | # Josh Peters wrote…

    Hey that's great; how do I turn this off? The Mac has had enough URL schemes setup by default and I really don't want to wait for some hole to be found in Textmate that can screw with anything on my system. I am sorry if this sounds harsh: I am a big fan of Textmate and enourage innovative programming, just not at the cost of security.

    I'm also certain that Macromates has the best of intentions with this URL scheme, but I would rather not chance anything.

  5. 26 Apr 2007 | # Allan Odgaard wrote…

    Josh Peters: Install RCDefaultApp. Then you can view all URL scheme handlers on your system, and disable those you do not feel comfortable with.

    As for the exploits and the txmt scheme: The exploits were possible because several of Apple’s URL schemes had (documented) ways to run code (the disk image scheme though indirectly allowed exploits because it had a way to place code on the users machine).

  6. 27 Apr 2007 | # Josh Peters wrote…

    Allan: thanks for the pointer to RCDefaultApp. I've used it before but forgot all of its capabilities.

    As for the exploits and the txmt scheme: I understand the Apple disk image hole, but I still prefer to avoid (in my opinion) extraneous ways for applications to interact.

    As for the documented part, what other commands does/will Textmate understand beyond "open"? If none, why have the "open" part at all?

  7. 27 Apr 2007 | # Allan Odgaard wrote…

    Josh: In addition to the open command, there is also register. This takes normal URL name and password parameters (e.g. txmt://Allan:«license»@register). The purpose of this is making registration easier (for the user) and such link is presented on the “Thanks for your purchase” page (and I might send HTML emails in the future, with such links).

    When opening such a link, TextMate will ask for confirmation. It doesn’t do this for open since it would be too intrusive, but I think I’ll do it for non-white listed files and folders in 2.0.

  8. 27 Apr 2007 | # Allan Odgaard wrote…

    Chris Adams: It should re-use the window, if the file is already open.

    If it doesn’t, the cause is most likely that the paths do not look the same to TextMate, for example because of symbolic links.

    Try a) ⌘-click the icon in the title bar of the open window and b) right-click your stack trace link and copy the link to the clipboard. Now compare the two paths.

    If they are identical, provide as much data (and/or isolate the problem), and I will look into.

    And btw sorry for not seeing your comment in the spam queue before now.

  9. 24 Nov 2007 | # What is a URL? wrote…

    I don't think that there should be two slashes after the "txmt:". In http urls the two slashes indicate that we will be giving an internet address. Local files usually have three slashes.

  10. 24 Nov 2007 | # Allan Odgaard wrote…

    The rationale behind the two slashes is that:

    1. It means the URL gets properly underlined in most contexts. As mentioned in a previous comment, I also have a register command, and since then I have also introduced another one. Both are likely to appear in email or similar where they cannot explicitly be marked up as URLs.

    2. The system’s NSURL class is used for handling the scheme, and it expects the two slashes.

  11. 21 Jan 2009 | # Craig Williams wrote…

    I would like to open urlencoded text from my website the same way it is done with AppleScript. Is this possible?

    AppleScript eg.

    <a href="applescript://com.apple.scripteditor?action=new&script=display%20dialog%20%22This%20is%20from%20a%20webpage%22">Open Script</a≶

    Will Open in Script Editor as

    display dialog "This is from a webpage"

  12. 27 Jan 2009 | # john p. wrote…

    Regarding tow and three slashes: As i understand things, the two slashes denoted a URL, wehter loval, file , http or ftp.

    The three slashes is , unsuprisingly or not, two + one; the one slash following the two for url, denotes the path / :

    e.g. * :~ mypooter$ file://etc/profile would look for file realative to the home folder, and not find it, unless you put it there.

    • :~ mypooter$ file:///etc/profile would look look for the same from the system root folder.

    So I have learnt. PLum

  13. 15 Sep 2009 | # Jakob Stoeck wrote…

    The link to Ruy is obsolete. The new working version: http://ruy.ca/2007/04/01/handling-txmt-urls-in-windows

Comments closed, you can use the mailing list for discussion.