4. Projects

Below, the term “project” is capitalized when it is referring to a Sublime Text Project, and in lower-case when it is referring to the general concept of a project (e.g. work involving many steps, or a software or authoring project, etc.).

The Sublime Text Project paradigm is remarkably flexible. It holds that every Sublime Text Window has exactly one Project open at all times. If you haven’t saved it or opened it as a Project, then it is the “anonymous Project”. But it is there and active, even if only in RAM. The current Project can be saved to re-open in a later session by:

Project > Save Project As...

Sublime Texts Projects can be anywhere (not necessarily in the same directory as the files in the Project), and can have any number of “content root” (a.k.a. Mount Point) directories in its structure. Those “content root” (Mount Point) directories do not need to correspond with where the Project file is located, although doing so can be helpful when you want to enter the .sublime-project file into the project’s source-code repository.

Projects in Sublime Text are made up of at least two files: the .sublime-project file, which contains the Project definition, and the .sublime-workspace file, which contains user-specific data, such as the open files, the modifications to each, and various application states such as what files were open, cursor positions, tab ordering, etc.. It is possible to have more than one .sublime-workspace file per Project, and either the workspace or the Project file can be opened (Project > Open Project...) to return to your “last session” with that Project, or to a particular session by opening the workspace file. You might want to have more than one workspace file if you regularly edit 2 or more different groups of files in that Project and the two tasks are logically separate.

To tell Sublime Text what files you want in the Project, you merely need to add the appropriate “content root” (Mount Point) directory or directories to it. The easy way to do so is to drag and drop each “content root” folder anywhere in a Sublime Text window to add to the current Project. Alternately, Project > Add Folder to Project....

As a general rule, the .sublime-project file can be checked into version control, whereas the .sublime-workspace file should not.

4.1. Creating a New Project

Keeping the above firmly in mind, creating a new Project is simple:

Close the current Project if one is open. This returns you to a new, empty “anonymous Project”.
Project > Save Project As... and save the current (anonymous) Project with the appropriate name and location for your new project.
Add the appropriate “content root” (Mount Point) directories to it.

Alternately, if an existing project provides most of what you need in the project (e.g. inclusions and exclusions of folders, files and indexing patterns), then from an open project, simply perform a Project > Save Project As... and then Project > Edit Project and make the modifications needed for that project.

4.2. Project File Format

You can use Project > Edit Project to directly modify the current Project file. This can be easier than File > Open when the file is not in the same directory as the file you are editing.

.sublime-project files are Sublime-relaxed-JSON format files, and support three top level sections:

“folders”, for the included folders,
“settings”, (optional) for editor-setting overrides, and
“build_systems”, (optional) for Project-specific build systems.

An example:

{
    "folders":
    [
        {
            "path": "src",
            "folder_exclude_patterns": ["backup", "build"],
            "follow_symlinks": true
        },
        {
            "path": "docs",
            "name": "Documentation",
            "file_exclude_patterns": ["*.css"]
        }
    ],
    "settings":
    {
        "tab_size": 8
    },
    "build_systems":
    [
        {
            "name": "List",
            "shell_cmd": "ls -l"
        }
    ]
}

4.2.1. “folders” Key

The “folders” key contains an array of “content root” objects. Each object must have a “path” key, which may be relative to the Project directory, or a fully qualified path.

Additional optional keys include:

name:: (string) A name used in place of the folder name in the Side Bar
file_include_patterns:: (array of strings) Patterns of files to include in the folder. Anything not matching these patterns will be excluded. This is checked before “file_exclude_patterns”.
file_exclude_patterns:: (array of strings) Patterns of files to exclude from the folder. This is added to the global setting of the same name. This is checked after “file_include_patterns”.
folder_include_patterns:: (array of strings) Patterns of folders to include from the folder. Anything not matching these patterns will be excluded. This is checked before “folder_exclude_patterns”.
folder_exclude_patterns:: (array of strings) Patterns of folders to exclude from the folder. This is added to the global setting of the same name. This is checked after “folder_include_patterns”.
binary_file_patterns:: (array of strings) Patterns of files to treat as binary files, and thus ignored in Goto Anything and Find in Files. This is only needed if this Project’s binary files differ from “binary_file_patterns” in Default/Preferences.sublime-settings.
index_include_patterns:: (array of strings) Patterns of files to index in the folder. This is added to the global setting of the same name. Anything not matching these patterns will be excluded from the index. This is checked before “index_exclude_patterns”.
index_exclude_patterns:: (array of strings) Patterns of files to excluding from indexing in the folder. This is added to the global setting of the same name. This is checked after “index_include_patterns”.
follow_symlinks:: (boolean) If symlinks should be followed when building the folder tree.

Converted Projects from earlier versions may have a “mount_points” entry under “folders”. If you wish to use the exclude patterns, you’ll need to change to the above format.

4.2.2. “settings” Key

Settings may be specified here using the “settings” key, and will override regular editor settings. They will not, however, override syntax-specific settings.

Note that only settings in the category Editor Settings may be controlled by a Project.

4.2.3. “build_systems” Key

“build_systems” specifies a list of inline Build Systems definitions. In addition to: the regular build system settings, a “name” must be specified for each one. Build systems listed here will be available via the regular Tools > Build Systems menu.