Projects - Reference

See also

Documentation on projects
Explains how to work with projects.

Project information is saved in metadata files that can be edited to allow advanced configuration other than adding or removing folders. To edit the project file of the currently active project via the Project → Edit Project menu. An anonymous project cannot be configured in any way, because no .sublime-project file exists for it.

File Format

Format JSON (with comments)
Extension .sublime-project
Name Any
Location Anywhere on your file system
Content Metadata for projects

Example

Project metadata is split across three topmost sections:

  • folders, for the included folders;
  • settings, for project-specific settings; and
  • build_systems, for project-specific build systems.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "folders":
    [
        {
            "path": "src",
            "folder_exclude_patterns": ["backup"]
        },
        {
            "path": "docs",
            "name": "Documentation",
            "file_exclude_patterns": ["*.css"]
        }
    ],
    "settings":
    {
        "tab_size": 8
    },
    "build_systems":
    [
        {
            "name": "List",
            "cmd": ["ls"]
        }
    ]
}

Sections

Folders

A list of folders that will be listed in the sidebar and defines the project scope.

path
Required. The path may be relative to the project directory or absolute. Use . for the directory the project file is in.
name
Optional. If present, it will appear in the side bar instead of the directory name.
folder_exclude_patterns
Optional. List of wildcard patterns. Folders matching the wildcard patterns will be excluded from the project.
folder_include_patterns
Optional. List of wildcard patterns. Folders matching the wildcard patterns will be included in the project.
file_exclude_patterns
Optional. List of wildcard patterns. Files matching the wildcard patterns will be excluded from the project.
file_include_patterns
Optional. List of wildcard patterns. Files matching the wildcard patterns will be included in the project.
follow_symlinks
Optional. If enabled, symlinks will be followed for path resolution.

Example:

{
    "folders":
    [
        {
            "path": ".",
            "folder_include_patterns": ["foo"],
            "file_exclude_patterns": ["*.html"]
        },
        {
            "path": "foo",
            "name": "foo <with HTML files>"
        }
    ]
}
Settings

A project may define project-specific settings that will only apply to files within that project. Project-specific settings override user settings, but not syntax-specific settings.

Almost all settings can be overridden (excluding global settings).

See also

The Settings Hierarchy
A detailed example for the order of precedence for settings.
Settings - Reference
Reference of available settings.
Build Systems

You can define project-specific build systems in a .sublime-project file. 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 that project.

See also

Build Systems - Reference
Documentation on build systems and their options.