How to actually set up subl (on Mac)

This post is a command-by-command walkthrough on how to set up subl, the command line tool that comes with the text editor Sublime Text. Once you've done this, you'll be able to use the subl command to open files and directories directly from your terminal. You'll also be able to make Sublime the default text editor used by command line tools such as git. I'll include instructions for git specifically, so that when you do git commit (for example) you can write your commit message in Sublime instead of vim, the default text editor in the Mac terminal.

Why this post?

Among text editors, Sublime is often recommended for beginners, because it's easier than vim or emacs. Still, I remember struggling with "simple" installation and configuration tasks as a beginner. The subl instructions from the Sublime documentation are just one step long, but in practice, you get errors and end up on Stack Overflow, piecing together the prerequisites that the documentation just blithely assumed you already knew. This kind of confused puzzling is actually totally normal in programming, and you get used to it with experience, but it can be demoralizing when you're starting out. So, for beginners, I've put together this one-stop-shop for getting Sublime set up as your default editor.

My assumptions

How to install the subl command line tool

Step one: First, we'll check that you have a ~/bin directory set up, and create one if you don't. In your terminal, enter these commands:

      cd ~

You should see a list of folders and files from your "home directory." Do you see bin listed among them? If not, enter this command before moving to step two:

      mkdir bin

Side note: cd ~ simply takes you to your home directory. It took me a long time to figure out that ~ is simply shorthand for your "home directory" path, which is usually something like /Users/aliceyu, with / representing your "root directory." This was surprisingly hard to google up.

Step two: Double-check that you have Sublime Text 2 installed in your root Applications folder. This will generally be the case if you're on your own computer and didn't do anything unusual when installing Sublime. To be sure, enter this command:

      ls /Applications

You should see Sublime Text listed among your applications. If not, you will need to download Sublime, or modify the command in step three if you have it installed elsewhere on your computer.

Step three: We'll create an "alias" of the subl file in your bin directory. It’s ok if you don’t quite know what that means. Copy and enter this command:

      sudo ln -s "/Applications/Sublime Text" ~/bin/subl

Step four: Now we'll edit your .bash_profile. It's just a little special file that lives in your home directory. (Sidenote: because it starts with a ".", it doesn’t show up when you type ls in your home directory, but it does show up if you type ls -a.)

Enter these commands:

      cd ~
      vim .bash_profile

This opens your .bash_profile file inside your terminal, using vim, the default text editor used by the Mac terminal. It may be disorienting if you're not used to vim, but stick with me.

Press “i” to get into vim “insert” mode.

Paste in this line:

      export PATH=$HOME/bin:$PATH

I recommend you ALSO add this line, which will make Sublime your default editor for most things (but make sure you have added the previous line too):

      export EDITOR='subl -w'

Press “esc” to get back into “command” mode.

Type this command and hit enter, to save and close the .bash_profile we’ve just edited:


Step five: You should now have the subl command line tool set up and working! Let’s test it out. First enter the command exit, which will close Terminal. Then reopen Terminal and try this command:

      subl --help

That ought to bring up the help text for Sublime, which means it worked. If you have any programming projects, cd into your project folder and run subl <filename> to open a file in Sublime Text, or run subl . to open the entire directory that you're in.

How to set Sublime as your default editor for git

This part is a bit easier. Again, I’m assuming you’ve already installed git. Open your terminal and enter this command:

      git config --global core.editor "subl -n -w"

I don’t believe it matters what directory you’re in. I ran mine from my home directory.

If that worked, the next time you do git commit, it should open Sublime and you’ll type your commit message there. Don’t forget you need to save and exit your commit message in order for your commit to go through. I use the keyboard shortcuts cmd s to save and cmd w to close the current tab in Sublime.

And that's it! Drop me a line if you found this helpful. Credit to the Sublime docs, the Github docs, this StackOverflow, and my friends Ross and Jake for helping me when I was doing this myself for the first time.