Whether you’re coding a Ruby on Rails site or writing a book, most text editing tasks involve working with more than one file. Juggling related files using Finder or Windows Explorer is a hassle and forces you to constantly switch applications to hunt for files.
Sublime’s projects alleviate this pain. Using projects, you can:
• Navigate effortlessly to related files.
• Maintain multiple workspaces, including separate sets open files and window layouts, reducing tab clutter.
• Improve code consistency among collaborators by specifying project-level overrides for settings such as white space.
• Automate repetitive tasks that need to be performed on a set of files.
I use several projects to organize different segments of my work, including my blog, this book, and several coding projects. Each of these workspaces is customized for the task at hand: The blog project has an open tab for a post that I’m working on, and another with some reference notes, and my blog’s folder is open in the sidebar. One of the coding projects has a couple of open files, an open folder and a horizontal split layout that allows me to move between a JavaScript file and an HTML file.
Thanks to Sublime’s projects, I can switch seamlessly between these workspaces without having to shuffle windows and close tabs, and it frees me from having to leave all of my in-progress work open in the same window.
How Projects Work
A Sublime project is a JSON-formatted settings file with a sublime-project extension. This file contains several pieces of information, including:
• Folders to be included in the project
• Custom settings for the project
• Custom build commands for the project
The project file is intended to be kept in the root directory of your project, and it can be checked into version control and shared among team members.
In addition to thesublime-projectfile, Sublime also creates asublime-workspacefile to manage details specific to your working environment, including which files you have open and any window layouts you’ve created. Don’t edit this file by hand or commit it into version control, or your team members will hunt you down…
Projects 12
Creating Projects
To create a new project:
1. Click Project | Save Project As ….
2. Browse to the root directory where your project files are saved.
3. Enter a name for the project file.
4. Click Save.
Mac OS X users have another way to create a new project: Simply drag a folder or group of files into the Sublime icon on the dock.
Adding Folders
Once the project file is created, it’s time to add some folders. I usually add the root folder for the site I’m working on. Any child folders inside of the root folder will automatically be included, as well as the files they contain.
To add a folder using the menu:
1. Click Project | Add Folder To Project … 2. Browse to the folder you want to add.
3. Click Open.
You can also drag-and-drop folders from a file explorer into the sidebar under the Folders header.
When you add folders to the project, Sublime automatically updates the.sublime-projectfile and saves the changes in the background.
To quickly clean out all folders in a project:
• Click Project | Remove all folders from project.
Opening Projects
As a convenience, Sublime automatically reloads the last open project when launched. But chances are you’ll need to bounce around among several projects frequently, and Sublime makes it easy.
To open an existing project:
Projects 13 1. Click Project | Open Project….
2. Browse to the project file.
3. Click Open.
Or, if the project is one you’ve opened recently:
1. Click Project | Recent Projects.
2. Select the project from the list of available choices.
The most convenient method is the Switch Project in Window feature, which is available from the menu as well as via a keyboard shortcut.
To invoke Switch Project in Window: {#switch-project-in-window}
1. Click Project | Switch Project in Window, or press Control+Command+P on Mac OS X or Ctrl+Alt+P on Windows or Linux. An input box appears, along with a list of available projects.
2. Type part of a project name. The input box supports fuzzy matching, so the list is filtered to projects that contain the entered characters.
3. Press Enter when the desired project is highlighted to open the project.
Multiple workspaces per project
Working on a major project often means that you need to shift contexts frequently. You might split your time between front end web coding and server-side development. Or perhaps you’re jumping back and forth between the feature you’re currently working on and one that’s just came back with a few issues from QA. And then there’s that emergency bug fix to the feature you worked on last sprint …
Each context shift comes with a small setup cost. There are files to open and close. You might have preferred arrangements of tab groups for different tasks: a three-column view for front end work so you can see HTML, CSS and JavaScript open side by side, two rows for back end work, with your source on top and your unit tests below. You jump between tasks a few times, and before you know it you have 27 unrelated tabs scattered across three tab groups.
Sublime’s workspaces are ideal for establishing different contexts within your project. They allow you to create and save multiple arrangements of tab groups and open files per project. You can even have multiple Sublime windows open with separate workspaces to allow you to jump back and forth between contexts quickly.
Version Difference!
Sublime Text 2 only supports one workspace per project.
Projects 14 Workspaces are JSON files with a.sublime-workspaceextension, and they contain everything from your open files and tab groups to your cursor position within those files and your unsaved changes.
If you’ve created a project, you already have a primary workspace file—Sublime creates one by default.
To create another workspace for the current project, click Project | New Workspace for Project.
A new Sublime window opens with a partial copy of your current workspace: Preferences like Side Bar visibility and open folders are carried across, but open tabs are not.
If you’re just looking to change a few files without disturbing your current workspace, you can use this new workspace as is and simply close it when you’re ready to return to your original workspace.
But if you might want to return to the workspace in the future, click Project | Save Workspace As
…. You can also use Save Workspace As to save a workspace from an ad hoc collection of open files without creating a whole project first.
Create a dot files workspace
Do yourself a favor and make a workspace for that assortment of system configuration files you’re endlessly tweaking.
To switch to a previously saved workspace within the current window, click Project | Open Recent and select the desired workspace, or use theSwitch Project in Window command, which opens a filterable list of recent projects and workspaces for you to choose from. If the workspace you’re looking for doesn’t appear in either list, click Project | Open Project … to browse to and open the workspace directly.
Bug alert!
As of Sublime Text 3 build 3047, opening a project or workspace by double-clicking the file in your file manager creates multiple Sublime windows, each with a separate copy of the project. This is a bug, as far as I can tell. You can work around the problem until it’s fixed by using Open Project when you want to use a project or workspace that isn’t in your recent projects list.
Navigating in Projects
Projects really shine when used in concert with the Go to anything feature. Since Go to anything searches all open files and folders, and projects give you control over which folders are open, you can effortlessly jump between files without using the mouse.
For example, say you’re working in a large JavaScript project, and you’ve added the root directory for your project.
Projects 15 If you’re editingindex.html, all you need to do to jump toscript/plugin/myplugin.jquery.jsis hit Command+P on Mac OS X or Ctrl+P on Windows or Linux. Then type myp and hit Enter. This is especially convenient when your project has a complex folder structure that’s a pain to navigate with the mouse.
Editing Project Files
While Sublime makes some changes to project files in the background, to really put projects to work, you’ll need to edit the files by hand.
To open the project for editing:
• Click Edit project. The project file opens in a new tab.
Project-Specific Settings
A well-customized project file can help keep files organized and consistently formatted, even with multiple team members contributing. They can also help automate routine tasks.
The project file has three elements:folders,settings, andbuild_settings.
Including folders
Thefolders element gives you fine-grained control over how Sublime handles folders within the project. When you add a folder to your project, Sublime adds a new element to thefoldersarray.
You can add folders by hand as well. Use relative paths here to make the project file work properly regardless of where the root folder is located.
Excluding files and folders
You can also specify folders, files and file types to exclude, both for the project as a whole or just specific subfolders.
This is particularly useful for avoiding cluttering up your sidebar with auto generated files. For example, if you’re working on a project that uses SASS or CoffeeScript, by default bothstyle.sass and style.css will show up in your sidebar and in the Go to anything menu. Specifying the following file exclude pattern hides compiled CSS and JavaScript files:
1 "file_exclude_patterns": ["*.css", "*.js"]
Alternately, you could exclude the entire compiledstylesfolder with the following:
Projects 16 1 "folder_exclude_patterns": ["styles"]
Overriding settings
Project files can specify overrides for some user preferences with thesettingselement. On a multi-member team, this can prevent irritations like inconsistent use of tabs and spaces for formatting, and, if the team agrees on spaces, how many spaces should constitute one tab width.
Here’s how you could enforce the use of two spaces for indenting code:
1 "settings":
2 {
3 "translate_tabs_to_spaces": true,
4 "tab_size": 2
5 }
Thebuild_systemselement allows you to specify a list of custom commands that will be available under the Tools | Build System menu. You can map just about any arbitrary command supported by your platform.
For example, the following (fairly useless) entry creates a menu item called List that runs thels command to print a list of the project’s files and folders in the Sublime console:
1 "build_systems":
• Compile.coffeeor.scssfiles prior to deploying a static website.
• Copy files to a staging server withsftporrsync.
• Running a custom bash or PowerShell script to remove stray build files.
Project File Example
Here’s an example project file from the Sublime Text documentation so you can see how the pieces fit together:
Projects 17