HowToContribute

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.

More generally, using svn with UTF files, you should have the following comment in your ~/.bash_profile. If not then begin checking out with:

export LC_CTYPE=en_US.UTF-8

Additionally, svn commands often work relative to the current working directory (show this with "pwd". You want to start from

cd ~/Library/Application\ Support/TextMate/Bundles

For brevity this step will be assumed (left out) in the following examples

Next, check out the bundle you want to improve. We will use the example of "improveThis"

svn co http://svn.textmate.org/trunk/Bundles/improveThis.tmbundle

After having checked out the bundle, reload all bundles from within TextMate ("Bundles→ Bundle Editor → Reload", 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/improveThis.tmbundle improveThis.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 improveThis.tmbundle 

You will see a list of Modified Updated, new and deleted items, something like this:

?      improveThis.tmbundle/Commands/Go To Method.tmCommand
M      improveThis.tmbundle/Commands/Insert Call.plist
?      improveThis.tmbundle/Snippets/Detach New.tmSnippet
M      improveThis.tmbundle/Snippets/Delegate.plist
M      improveThis.tmbundle/Snippets/Dictionary (dict).plist
M      improveThis.tmbundle/Snippets/AutoreleasePool (pool).plist
M      improveThis.tmbundle/Snippets/Array (array).plist
M      improveThis.tmbundle/Syntaxes/improveThis.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 "improveThis.tmbundle/Commands/Go To Method.tmCommand"
svn add "improveThis.tmbundle/Snippets/Detach New.tmSnippet"

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

svn diff improveThis.tmbundle >improveThis.patch

Here we redirect the svn output to go into the improveThis.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 who is knowledgeable about the bundle you wish to help improve.

If you send your patch using Mail.app then zip the file first - Mail has a tendency to mangle leading whitespace for text in the body, which renders the patch unusable.

If you are sending the patch via IRC, 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 improveThis.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.