This page describes how you can contribute back with improvements to one or more of the TextMate bundles.

Checking out the Bundle

You should start by checking out the latest version of the bundle you want to improve into ~/Library/Application Support/TextMate/Bundles.

For example if you want to improve the Objective-C bundle, you would execute:

# you should preferably move this to ~/.bash_profile
export LC_CTYPE=en_US.UTF-8



# change to the proper directory, we may leave this
# out in the following examples for brevity
cd ~/Library/Application\ Support/TextMate/Bundles



svn co http://svn.textmate.org/trunk/Bundles/Objective-C.tmbundle

After having checked out this bundle, be sure to select Bundles → Bundle Editor → Reload Bundles from within TextMate or from shell run:

osascript -e 'tell app "TextMate" to reload bundles'

Normally it is not recommended that you checkout bundles to the above location, because when you change the bundle items from inside TextMate, it saves changes to ~/Library/…, potentially leading to merge conflicts if the files are updated in an incompatible way on the server — but in this case we actually do want to edit the default bundle directly, so the normal rule does not apply.

If you already have done a full checkout of the repository to /Library then you can instead do a symbolic link, e.g. using:

cd ~/Library/Application\ Support/TextMate/Bundles
ln -s /Library/Application\ Support/TextMate/Bundles/Objective-C.tmbundle Objective-C.tmbundle

Changing the Files

Generally make your changes from TextMate’s bundle editor, this preserves file names on disk even if you rename the items, and will ensure that the info.plist in the bundle (which stores the ordering of items, the bundle’s menu structure, etc.) is updated correctly.

Learning Which Files You Changed

After you have made changes, you can run the following command from shell to see how your version of the bundle looks compared to the default version:

cd ~/Library/Application\ Support/TextMate/Bundles
svn st Objective-C.tmbundle 

In my case the result looks like this:

?      Objective-C.tmbundle/Commands/Go To Method Definition.tmCommand
M      Objective-C.tmbundle/Commands/Insert Call to Super.plist
?      Objective-C.tmbundle/Snippets/Detach New NSThread.tmSnippet
M      Objective-C.tmbundle/Snippets/Delegate Responds to Selector.plist
M      Objective-C.tmbundle/Snippets/040 NSDictionary (dict).plist
M      Objective-C.tmbundle/Snippets/NSAutoreleasePool (pool).plist
M      Objective-C.tmbundle/Snippets/030 NSArray (array).plist
M      Objective-C.tmbundle/Syntaxes/Objective-C++.plist

The items with a ? are items added and not present in the default bundle, the items with an M are locally modified.

Generating a Patch

To generate a patch which contains all your changes you need to first add those files which are new, for example to add the two new files in the Objective-C bundle we do:

svn add "Objective-C.tmbundle/Commands/Go To Method Definition.tmCommand"
svn add "Objective-C.tmbundle/Snippets/Detach New NSThread.tmSnippet"

Then to get a patch for the entire bundle, we execute:

svn diff Objective-C.tmbundle >obj-c.patch

Here we redirect the svn output to go into the obj-c.patch file. If you wish to send a patch for only a subset of the files you have changed then you can specify specific files as the argument to svn diff.

Submitting the Patch

Since the different bundles have different maintainers, it is generally best to send the patch to the TextMate mailing list, or join the ##textmate IRC channel at freenode, and see if there is anyone online which is knowledgeable about the bundle you wish to help improve.

If you send your patch using Apple’s Mail application then do zip the file first. This is only because Mail has a tendency to mangle leading whitespace for text in the body, which renders the patch unusable.

If you are sending the patch to someone via IRC, you can open the patch file in TextMate, select all, and use the “Paste Selection Online → Send to Clipboard” command on ⌃⌥⇧V. This will paste the patch to <http://pastie.textmate.org/> and if you are using Colloquy, offers you to have the resulting URL sent directly to the ##textmate room.

Handling the Updated Bundle

When your patch has been accepted, you should update your local checkout of the bundle using:

svn up Objective-C.tmbundle

It will show you which files are then updated. Those preceded with a G are files where you had local changes, but svn was able to merge your changes with those on the server without problems.

If you get a C it means there was a conflict merging the local copy with the server version.

If you don’t actually have local changes you want to keep (which is likely, since you submitted them to be in the default bundle) the easiest is just to remove the bundle or the problematic items and do a new checkout.

However, the way to resolve a merge conflict is to load the file into a text editor, then locate all the lines with <<<<<<<< and >>>>>>>>, those mark where svn was unable to merge your local changes with those on the server. Merge this manually.

When you are done merging a file, you need to run:

svn resolved «file»

This tells svn that you have resolved the conflict. This will then remove the «file».mine and associated files, which appeared after the conflict.