projects.md

title
Projects

Projects

::: info See Also Documentation on projects : Explains how to work with projects.

Official Documentation on projects : May provide more up-to-date details. :::

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	Description
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.

{
    "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"]
        }
    ]
}

Folders

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

::: tip Pattern precedence The include patterns are applied first, effectively excluding everything that is not matched by them. Afterwards, the exclude patterns further exclude files or folders from the project.

:::

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).

::: info See Also 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.

::: info See Also Build Systems reference : Documentation on build systems and their options. :::