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:
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 () 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, .
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”.
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 and then and make the modifications needed for that project.
4.2. Project File Format
You can use to directly modify the current Project file. This can be easier than when the file is not in the same directory as the file you are editing.
.sublime-project files are JSONC 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 applied 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 applied 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 applied 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 applied 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 applied before “index_exclude_patterns”. See Indexing and Official Indexing Docs for more details about Sublime Text Indexing and its settings.
- 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 applied 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 menu.
4.3. Template Project File
Here is a useful .sublime-project template you can use on your system.
Like the Sublime Text default settings file, it contains the above
documentation to make it easier to use and edit project files when you
need to.
{
"folders": [
/*-----------------------------------------------------------------
* Array of Objects: Each object must have a "path" key, which may
* be relative to the project directory, or a fully qualified path.
* The other keys shown below are optional.
*
* For simple projects, it is often enough to only have a "path"
* and sometimes a "name" entry, making the project file more
* readable.
*-----------------------------------------------------------------*/
{
/*-------------------------------------------------------------
* "name": String: (optional) Name used in place of folder
* in Side Bar
*-------------------------------------------------------------*/
"name": "name",
/*-------------------------------------------------------------
* "path": String: (required) Path to top-level folder
* (mount point) that will be added to the Side Bar in the
* order of appearance in the "folders" list.
*-------------------------------------------------------------*/
"path": "E:\\Vics Documents\\References\\",
/*-------------------------------------------------------------
* Loading Sequence
*
* The include patterns below are applied first, effectively
* excluding everything that is not matched by them.
* Afterwards, the exclude patterns further exclude files or
* folders from the project.
*-------------------------------------------------------------*/
"index_include_patterns": [
/*---------------------------------------------------------
* Array of Strings: (optional) Patterns of files to index
* in the folder. Anything not matching these patterns
* will be excluded from the index. This is applied before
* "index_exclude_patterns".
*
* CAUTION: if anything is included in this list, then
* EVERYTHING ELSE is excluded. If you want the project
* to index all files (perhaps with some exceptions) then
* delete this entry.
*---------------------------------------------------------*/
"*.C",
"*.c",
"*.c++",
"*.cc",
"*.cmd",
"*.cpp",
"*.css",
"*.cxx",
"*.H",
"*.h",
"*.h++",
"*.hh",
"*.hpp",
"*.hxx",
"*.inc",
"*.inl",
"*.ipp",
"*.ixx",
"*.m",
"*.pl",
"*.pm",
"*.py",
],
"file_include_patterns": [
/*---------------------------------------------------------
* Array of Strings: (optional) Patterns of files to
* include from the folder. Anything not matching these
* patterns will be excluded. This is applied before
* "file_exclude_patterns".
*
* CAUTION: if anything is included in this list, then
* EVERYTHING ELSE is excluded. If you want the project
* to include all files (perhaps with some exceptions) then
* delete this entry.
*---------------------------------------------------------*/
],
"folder_include_patterns": [
/*---------------------------------------------------------
* Array of Strings: (optional) Patterns of folders to
* include from the folder. Anything not matching these
* patterns will be excluded. This is applied before
* "folder_exclude_patterns".
*
* CAUTION: if anything is included in this list, then
* EVERYTHING ELSE is excluded. If you want the project
* to include all folders (perhaps with some exceptions)
* then delete this entry.
*---------------------------------------------------------*/
],
"index_exclude_patterns": [
/*---------------------------------------------------------
* Array of Strings: (optional) Patterns of files to
* excluding from indexing in the folder. This is added to
* the global setting of the same name. This is applied
* after "index_include_patterns".
*---------------------------------------------------------*/
],
"file_exclude_patterns": [
/*---------------------------------------------------------
* Array of Strings: (optional) Patterns of files to
* exclude from the folder. This is added to the global
* setting of the same name. This is applied after
* "file_include_patterns".
*---------------------------------------------------------*/
"*.mep",
"*.url",
],
"folder_exclude_patterns": [
/*---------------------------------------------------------
* Array of Strings: (optional) Patterns of folders to
* exclude from the folder. This is added to the global
* setting of the same name. This is applied after
* "folder_include_patterns".
*---------------------------------------------------------*/
"doctrees",
"__pycache__",
".mypy_cache",
],
"binary_file_patterns": [
/*---------------------------------------------------------
* Array of Strings: (optional) Patterns of files to treat
* as binary files, in addition to "binary_file_patterns"
* in settings. Files matching these wildcards will show
* up in the Side Bar, but are not listed in `Goto Anything`
* and are skipped in `Find in Files` searches.
*---------------------------------------------------------*/
"*.gz",
"*.7z",
"*.bz2",
"*.Z",
"*.tar",
"*.iso",
"*.o",
"*.obj",
"*.so",
"*.lib",
"*.pdb",
"*.dll",
"*.ex_",
"*.exe",
"*.elf",
"*.msi",
"*.cab",
"*.zst",
"*.xpi",
"*.xlsx",
"*.doc",
"*.docx",
"*.odt",
"*.odb",
"*.ppt",
"*.woff",
"*.woff2",
"*.ttf",
"*.otf",
"*.{",
"*.mp4",
"*.gif",
"*.chm",
"*.lnk",
"*.sys",
"*.bin",
"*.sqlite",
"*.suo",
"*.db",
"*.ipch",
"*.exp",
],
/*-------------------------------------------------------------
* Boolean: (optional) Follow symlinks when building folder tree?
*-------------------------------------------------------------*/
"follow_symlinks": true
},
],
"settings": {
/*-----------------------------------------------------------------
* (optional) Project-specific settings override user settings, but
* not syntax-specific settings. (Only editor settings have an
* effect here; UI and application-behavior settings do not. These
* are in the lower 1/3 of the main settings file. These sections
* can be observed by their titles in header comments on lines 577
* and 702 respectively as of build 4200.
*-----------------------------------------------------------------*/
"tab_size": 4,
"translate_tabs_to_spaces": true,
},
"build_systems": [
/*-----------------------------------------------------------------
* (optional) Project-specific build systems go here. Build
* systems in projects follow the same rules as conventional build
* system, except a name must be specified for each. They will
* show up in the
*
* Tools > Build Systems
*
* menu and are selectable in the `Build With` popup, but only in
* this project.
*-----------------------------------------------------------------*/
{
"name": "List",
"cmd": ["ls"]
}
]
}