Home

Some Helpful Tips

I'm compiling these from issues other users have had…

Keybindings

This information is not specific to the FileDiffs command. Any package that exposes a command can be assigned a custom key binding this way. Rather than provide defaults that the user can override, I prefer to provide a file called Example.sublime-keymap and leave it up to the user to add key bindings as she/he sees fit.

Locating the user key binding file

• On OS X: Sublime Text 2 → Preferences → Key bindings - User (menu is just named Sublime Text in version 3)
• On Windows and Linux: Preferences → Key bindings - User

Locating Example.sublime-keymap

In Sublime Text 2, the Example.sublime-keymap file is located in the FileDiffs folder within the Packages folder:

• Windows: %APPDATA%\Sublime Text 2 (e.g. C:\Users\username\AppData\Roaming\Sublime Text 2\Packages)
• OS X: ~/Library/Application Support/Sublime Text 2 (e.g. /Users/username/Library/Application Support/Sublime Text 2/Packages)
• Linux: ~/.config/sublime-text-2/Packages (e.g. /home/username/.config/sublime-text-2/Packages)

This folder can also be opened in your operating system's file manager (Windows Explorer, Finder, Nautilus, etc.) by selecting Preferences → Browse Packages… (this is found under the Sublime Text 2 or Sublime Text menu in OS X).

If you are using Sublime Text 3, by default packages are installed as .sublime-package zip files in Sublime's Installed Packages folder (unless the developer chooses otherwise). The easiest way to access their contents is to install @skuroda's PackageResourceViewer plugin. Once installed, open the Command Palette (CtrlShiftP on Windows and Linux, ⌘ShiftP on OS X), type in prv for PackageResourceViewer, then select either View Package Resource or Extract Package. If you choose the View option, you can then scroll through a series of menus to select the package, subdirectory (if necessary), and filename of the file you're interested in. For the purpose of examining the Examples.sublime-keymap file and copying any relevant entries to your personal keymap file, this option is by far the best one. The Extract option allows you to pick which package you'd like to extract, then the entire directory structure is recreated in your Packages folder (see warning about this option below):

• Windows: %APPDATA%\Sublime Text 3 (e.g. C:\Users\username\AppData\Roaming\Sublime Text 3\Packages)
• OS X: ~/Library/Application Support/Sublime Text 3 (e.g. /Users/username/Library/Application Support/Sublime Text 3/Packages)
• Linux: ~/.config/sublime-text-3/Packages (e.g. /home/username/.config/sublime-text-3/Packages)

You can now view (and edit) any file you choose. Please be aware, however, that any file(s) in Packages/PluginName will override any identically-named file(s) contained in the .sublime-package archive. Additionally, upgrades via Package Control *will not *apply to Packages/PluginName, only to the .sublime-package file in Installed Packages. Therefore, if you extract the entire package using the PackageResourceViewer: Extract Package option, you are essentially blocking any future package upgrades from being applied to your system, unless you remove the directory and re-extract it (if desired) from the upgraded version. Unless you have a good reason to (and know what you're doing), it is highly recommended to just use the View option.

Add external diff tool

1. Open Preferences → Package Settings → FileDiffs → Settings - Default.

2. Open Preferences → Package Settings → FileDiffs → Settings - User.

3. Copy the entire contents of Default to User, then close Default.

4. Uncomment one of the examples or write your own command to open an external diff tool of your choice.

IMPORTANT: Don't forget to make a correct symlink (e.g. in /usr/bin or /usr/local/bin) pointing to the command line tool of your external diff tool if it is not already in your path. For example, if you're running OS X and you want to use Kaleidoscope (note the menu is just named Sublime Text in version 3):

1. Add your key bindings:
   • Open Sublime Text 2 → Preferences → Key Bindings - User and add { "keys": ["ctrl+shift+d"], "command": "file_diff_menu" }.
   • Here's an example.
2. Add a command:
   • Open Sublime Text 2 → Preferences → Package Settings → FileDiffs → Settings - User and add "cmd": ["ksdiff", "$file1", "$file2"].
   • Here's an example (just uncomment the ksdiff line).
3. Create a symlink:
   • Open Terminal and run sudo ln -s /Applications/Kaleidoscope.app/Contents/MacOS/ksdiff /usr/bin; this will create a symbolic link to the ksdiff command line tool.
4. Compare files:
   • Open two files that you want to compare and run your key binding (CtrlShiftD).
   • From the menu that opens (file_diff_menu, see below), choose Diff file with Open Tab…. If everything is setup correctly, then Kaleidoscope.app will open and you can start comparing the diffs.