This is a tentative version! This bundle will be rewritten entirely in the near future!
"GetBundles" provides an easy to use interface to install available TextMate bundles which are hosted on macromates' svn repositories and on github.com.
# Requirements
The computer has to be connected to the internet.
## svn Repositories
In order to check out bundles hosted on svn repositories, the underlying script makes usage of the UNIX command `svn`. On Mac OSX 10.5.x `svn` is pre-installed. On Mac OSX 10.4.x it must be manually installed ([see here](http://www.collab.net/downloads/community/)). Furthermore the script recognizes if the user has set TextMate's shell variable `TM_SVN`. See also [here](#sect_2.1).
## git Repositories
Bundles hosted in a git repository ([a fast version control system](http://git.or.cz/)) on [github.com](http://github.com/ "Secure Git hosting and collaborative development — GitHub") can be also installed by downloading as a zip archive. Thus it is not necessary to install `git`. However, if `git` is installed and the user did not check the option "using zip archive" in the Advanced Drawer, then `git clone` will be used to install the bundle(s). Furthermore the script recognizes if the user has set TextMate's shell variable `TM_GIT`. See also [here](#sect_2.2).
For installing a bundle by downloading it as zip archive the script needs `unzip`. This command should be installed by default on any Mac OSX system.
### using `git clone` behind a firewall ###
`git clone` uses port 9148. If you are behind a firewall this port might be denied. To check run the following command in the Terminal:
cd ~/Desktop
git clone git://github.com/timcharper/git-tmbundle.git
If nothing happens after "initializing an empty Git repository" or if you see an error message like "fatal: unable to connect a socket (Operation timed out)" then it is very likely that a firewall (mostly not your firewall on the Mac) denies that port.
One simple solution is to install the bundle by downloading it as zip archive (zipball) (see "Advanced Drawer" [here](#sect_4.1.2.1)).
However, if you need to execute `git clone` then you can try the following two things:
* Ask your IT department to open that port for you.
* Set up `git` to use a proxy, via the shell variable `GIT_PROXY_COMMAND`.
To set up proxy support in `git`, do the following:
* check whether the UNIX command `socket` is installed on your system. If not, download the source code from http://www.bibiko.de/socket-1.1.mac.zip , decompress it, and run `make; sudo make install` in the Terminal.
* ask your IT department for the Web Proxy (HTTP) `PROXY_URL` and the port, `PORT` (maybe it is already set in "System Preferences" > "Network" > "Advanced" > "Proxies" )
* write a shell script e.g. `proxy-git.sh`:
* save the script to somewhere in your path, like `/usr/local/bin` and make sure that the script is executable
* add this to the file ~/.profile
export GIT\_PROXY\_COMMAND=PATH\_TO/proxy-git.sh
# General Operating Mode
After invoking "GetBundles" the script scans the following repositories for TextMate bundles:
* [http://macromates.com/svn/Bundles/trunk/Bundles/](http://macromates.com/svn/Bundles/trunk/Bundles/) (Bundles B)
* [http://macromates.com/svn/Bundles/trunk/Review/Bundles/](http://macromates.com/svn/Bundles/trunk/Review/Bundles/) (Review R)
* [http://github.com/](http://github.com/) (GitHub G)
In order to increase the speed of scanning the svn repositories, descriptions are saved locally. If a new bundle was uploaded to a svn repository and the local copy of the descriptions does not contain its description, you will be notified by a message to "Update the Descriptions". This can be done by invoking the "Gear Action Menu" command "Update Descriptions".
It is recommended that you regularly update the locally saved descriptions, otherwise the script will not recognize modified bundle descriptions.
The descriptions of all bundles hosted on github.com will not be cached locally.
The entire scanning process can be cancelled by hitting or by clicking into the spinning wheel. The bundle list can be rescanned using the "Gear Action Menu" command "Rescan Bundle List".
Once you have the list of bundles, you can select one or more and hit to install it/them. After installtion, TextMate will be forced to execute "Reload Bundles", making them appeat in the Bundles menu. Installation can be cancelled by hitting , as long as the script has not already physically installed that bundle (it uses a temporary folder first). If a given bundle is already installed on your system, the script will ask you whether that bundle should really be installed. If the you confirm this, the "old" bundle will be renamed into "THEBUNDLENAME.tmbundleTIMESTAMP" for safety reasons.
*Example* Java.tmbundle09022008085943 means a backup of Java.tmbundle done at Feb 9 2008, 08:59:43.
The default installation path is `~/Library/Application Support/TextMate/Pristine Copy/Bundles` (Users Lib Pristine). This path can be changed in the "Advanced Drawer" dialog (more detail [here](#sect_4)). Please note that for svn repositories, the script will perform a clean svn checkout. To avoid certain conflicts it is recommended if you want to work with a given bundle via `svn` afterwards, you change its installation path to `~/Library/Application Support/TextMate/Bundles` (Users Lib Bundles). The same is true for installing bundles from github.com using `git clone`.
"GetBundles" also allows you to do a complete svn checkout of TextMate's Support Library from `http://macromates.com/svn/Bundles/trunk/Support/` into `/Library/Application Support/TextMate`. This process can be invoked by hitting " in the "Advanced Drawer" dialog.
In order to close the "GetBundles" dialog simply hit the or press .
Hint The underlying script is written in Ruby 1.8 as has been tested on Mac OSX 10.4.x and 10.5.x. The script will not run under Ruby 1.9. If Ruby 1.9 is officially released the script will be updated as necesary.
## svn Installation ##
The script will install a bundle by using this command template:
export LC_CTYPE=en_US.UTF-8
mkdir -p /tmp/TM_GetBundlesTEMP
cd /tmp/TM_GetBundlesTEMP
svn co --no-auth-cache --non-interactive URL_TO_A_BUNDLE.tmbundle
if info.plist is found
if BUNDLE.tmbundle already exists in INST_FOLDER
ask for replacing
if YES
rename old BUNDLE by appending a time stamp
else
exit
else
cp -R /tmp/TM_GetBundlesTEMP/BUNDLE.tmbundle INST_FOLDER.BUNDLE.tmbundle
else
exit
rm -f /tmp/TM_GetBundlesTEMP
Reload Bundles
If you want to use another `svn` client you can set `TM_SVN` as a TextMate shell variable in TextMate's preferences.
## git Installation ##
### git clone ###
If `git` is installed and the checkbox "using zip archive" in the "Advanced Drawer" is unchecked, the script will use the following command template:
mkdir -p /tmp/TM_GetBundlesTEMP
git clone URL_TO_A_BUNDLE.git /tmp/TM_GetBundlesTEMP/BUNDLE
if info.plist is found
if BUNDLE.tmbundle already exists in INST_FOLDER
ask for replacing
if YES
rename old BUNDLE by appending a time stamp
else
exit
else
cp -R /tmp/TM_GetBundlesTEMP/BUNDLE.tmbundle INST_FOLDER.BUNDLE.tmbundle
else
exit
rm -f /tmp/TM_GetBundlesTEMP
Reload Bundles
If you want to use another `git` client you can set `TM_GIT` as a TextMate shell variable in TextMate's preferences.
### git via downloading the zip archive ###
If `git` is not installed or the checkbox "using zip archive" in the "Advanced Drawer" is checked the script will use this command template:
download URLBUNDLE/zipball/master to /tmp/TM_GetBundlesTEMP/github.tmbundle.zip
unzip /tmp/TM_GetBundlesTEMP/github.tmbundle.zip -d /tmp/TM_GetBundlesTEMP/
remove ID by using unzip
if info.plist is found
if BUNDLE.tmbundle already exists in INST_FOLDER
ask for replacing
if YES
rename old BUNDLE by appending a time stamp
else
exit
else
cp -R /tmp/TM_GetBundlesTEMP/BUNDLE.tmbundle INST_FOLDER.BUNDLE.tmbundle
else
exit
rm -f /tmp/TM_GetBundlesTEMP
Reload Bundles
# Interface #
## Main Dialog ##
![Main Dialog](images/img_gui.png)
Dialog on Mac OSX 10.4.x differs slightly
The core of the dialog is a table listing all discovered bundles.
The first column indicates where the bundle is hosted:
The second column, "Name", displays the bundle's name. Please note that names for bundles hosted on GitHub could differ from the actual installed bundle name in TextMate, according to the name given by the git project's author.
The third column, "Description", displays the description of each bundle, taken from the `info.plist` for svn repositories and the description tag for git repositories.
All three columns can be sorted by clicking on appropriate part of the header.
It is possible to select more than one bundle at the same time, and to install all of them.
### Filtering/Searching ###
You can use the search field to enter a search term. This will look for bundles containing the search term, and is case insensitive. This process searches the fields "name" and "description" (and "author" for github.com hosted bundles). The list can be further filtered using these buttons
![](images/img_repo_filter.png)
which will display only those bundles which are hosted on the selected repository:
### Get Bundle Info ###
Opens a new window containing available details about the selected bundle. The data will be downloaded from the repository.
### Gear Action Menu ###
![](images/img_gear_menu.png)
The "Gear Action Menu" provides some additional commands:
#### Update Descriptions / Update (x missing) ####
This command updates the local copy of descriptions for all svn repositories. It is recommended that this is done regularly in order to be up-to-date. The underlying script will recognize if a new bundle was added but **not** if the description of an pre-existing bundle was changed.
If some descriptions are not found in the local copy of the descriptions, the name of that command will be changed into "Update (x missing)" indicating that x descriptions are missing.
#### Rescan Bundle List ####
This command deletes the current list of bundles and rescans all repositories.
#### Show Activity Log Drawer ####
Opens or closes a drawer displaying GetBundles' console log file. The path to the log file is ~/Library/Logs/TextMateGetBundles.log. See also [here](#sect_5).
#### Show Advanced Drawer ####
Opens or closes a drawer with advanced commands. More details [here](#sect_4).
### Message Field + Cancel current Task ###
![](images/img_message.png)
All activities and warnings will be shown in this message field. To cancel the current task, it is possible to click the spinning wheel or hit . While installing a bundle, it is possible to cancel the process as long as the script has not yet physically installed the bundle.
### Show Help ###
Opens that "Help" window.
# Advanced Drawer #
![](images/img_adv_drawer.png)
### Installation
#### Target Folder ####
By using this pull down menu you can specify the installation folder for all selected bundles.
The default installation folder is **Users Lib Pristine**. This is the same folder that will be chosen if you install a bundle by double-clicking a downloaded bundle. If you want to use `svn` or `git` afterwards with a bundle, it is recommended that you choose **Users Lib Bundles**. If you want the installed bundles to be available for all users, choose **Lib Bundles**.
*Note:* **App Bundles** as installation folder should only be used in exceptional cases!
For testing purposes, you can choose **Users Desktop** or **Users Downloads** as the installation folder. Bundles which are downloaded here will **not** be installed.
#### Timeout ####
Each task is wrapped in a timeout block. This means that after x seconds (default 30) the task will be interrupted and a warning message will be displayed. If you open the "Activity Log Drawer" and you see that the script actually did an `svn checkout` or `git clone` you can increase the "Timeout". This can happen if you are using a slow internet connection, or the host is slow to respond.
If you want to cancel the current task you can press or click into the spinning wheel.
### git Installation ###
#### using zip archive ####
If you check this checkbox you can tell the script to install a bundle hosted on GitHub by downloading the zip archive (zipball), even if `git` is installed. This is especially useful if you have installed `git` but are sitting behind a firewall which denies the git port.
### Reveal Target Folder in Finder ###
This opens the selected folder in "Finder".
### Open Bundle Editor ###
This opens TextMate's "Bundle Editor".
### Update Support Folder ###
By default TextMate, ships with a support folder located in PathToTextMate.app`/Contents/SharedSupport/Support`. After downloading and installing TextMate for the first time or after a new release, the development of TextMate's bundles and additional scripts etc. will be continued. Due to that fact that bundles make makes use of new or changed features in the "Support Folder", it is sometimes necessary to update it.
An update will be installed into `/Library/Application Support/TextMate/Support`. After this update TextMate's shell variable `TM_SUPPORT_PATH` will be set to that folder.
# Activity Log Drawer #
![](images/img_act_log.png)
This drawer shows the current content of the log file ~/Library/Logs/TextMateGetBundles.log. The log file will be overwritten each time if you invoke "GetBundles".
# Additional Keyboard Shortcuts #
Install selected bundle(s)
Get details about selected bundle
Cancel current task
Open "Gear Action Menu"
Open/Close "Activity Log Drawer"
Open/Close "Advanced Drawer"
Close the "GetBundles" dialog
# Used Shell Variables
TM_SVN
absolute path to the `svn` client
TM_GIT
absolute path to the `git` client
Both variables can be set in TextMate's Preferences, under the item "Advanced".
# Troubleshooting & FAQ #
* "GetBundles" said that no `svn` client is found. What can I do?
> There are two possible reasons for that: ❶ You haven't yet installed an `svn` client. If so, have a look [here](http://www.collab.net/downloads/community/) and install a client (on Mac OSX 10.5.x it is pre-installed). ❷ TextMate can't find `svn` in `$PATH`. If so, set TextMate's shell variable `TM_SVN` accordingly.
* Why is a known bundle hosted on github.com not listed?
> There is a convention for naming TextMate bundles hosted on github.com. The project name should end with either "-tmbundle" or ".tmbundle". Due to the fact that not all of bundles follow this convention, the script is uses github's search API. The search terms are "tmbundle", "textmate", and "bundle". Only those projects which end with "tmbundle","bundle", "textmate bundle", or "tm bundle" are listed. Furthermore, if one of the following key phrases is found within the description tag: "my own", "my personal", "personal bundle", "obsolete", "deprecated", or "work in progress" then the bundle won't be listed. Another convention is that the bundle structure must be at the project's root level, i.e. not hidden in a subfolder of that project.
* I try to filter one repository, but it is empty. Why?
> It could happen that one repository is down or not accessible. In this case, the script will skip it. If the list is completely empty, it is very likely that you are not connected to the internet. Also ensure that you have cleared the search field.
* I press the Help button but no "Help" is shown. Why?
> Due to an internal issue, the script has to call the bundle's "Help" command by using AppleScript. This AppleScript only works properly if you have enabled access for assistive devices in "System Preferences" > "Universal Access" > "Enable access for assistive devices".
* The computer beeps if I press the Help button. Why?
> Due to an internal issue the script has to order out the front most document window. This is done by a command which is misused. This issue will be fixed in the near future. In other words don't worry about it.
* I read the message: "Please check the Activity Log". What should I do?
> Press or open the "Gear Action Menu" and chose "Show Activity Log". Another option is to look at the log file here.
* How can I cancel the current task?
> Simply press the or click the spinning wheel. Please note that the physical installation of a bundle cannot be cancelled for safety reasons.
* What does: "No info.plist is found" mean?
> Each bundle must contain a file called "info.plist", otherwise TextMate is unable to install it properly. If you have encountered this case, please mail it to TextMate's mailing list (textmate@lists.macromates.com).
* What does "…not yet downloaded…" mean in the description?
> This phrase will only be displayed if the local copy of your svn descriptions doesn't contain a description for that bundle. To update the local copy simply go to the "Gear Action Menu" and invoke "Update (x missing)".
* Why does the name of a bundle listed in "GetBundles" differ to the actually installed name?
> This could happen esp. for bundles hosted on GitHub. The actual name shown in TextMate's Bundles list is set in the file "info.plist". Within the dialog's list, the name of that project will be shown in the column "name", **not** the name set in "info.plist".
* While installing a bundle a "timeout" message appears. Why?
> There are several reasons for this. ❶ Something went wrong during the installation, i.e. no e.g. connection to the host. ❷ The host's response was too slow. To fix this, you can increase the timeout. See [here](#sect_4.1.1.2). ❸ Some commands cannot be executed for some reasons (not found or no permission). . ❹ If you were installing a bundle using `git clone` and you are sure that the host is not down, it is very likely that a firewall is blocking `git`'s port 9148. If so please read more [here](#sect_1.2.1).
**In any case, please check the "Activity Log"**
* The description in the list differs to that one in the Info Window. Why?
> There is a convention to "info.plist"'s description key: In the dialog everything before the HTML tag <hr> will be displayed as short description (without any other HTML tags). If the description contains the HTML tag <hr> everything after that tag will be shown as long description.
* I want to reconstruct an overwritten bundle. How can I do this?
> If you replaced an existing bundle, the old bundle will have been renamed according to BUNDLENAME.tmbundleTIMESTAMP. Simply delete BUNDLENAME.tmbundle, rename BUNDLENAME.tmbundleTIMESTAMP to BUNDLENAME.tmbundle and perform "Reload Bundles".
# Main Bundle Maintainer
***Date: Oct 10 2008***