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
More generally, using svn with UTF files, you should have the following comment in your ~/.bash_profile. If not then begin checking out with:
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
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
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
>>>>>>>>, 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»
svn that you have resolved the conflict. This will then remove the
«file».mine and associated files, which appeared after the conflict.