Documentation Projects

Projects in Sublime Text are made up of 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 and the modifications to each.

As a general rule, the .sublime-project file would be checked into version control, while the .sublime-workspace file would not.

Project Format

.sublime-project files are JSON, and support three top level sections: folders, for the included folders, settings, for file-setting overrides, and build_systems, for project specific build systems. An example:

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

Folders

Each folder must have a path key, which may be relative to the project directory, or a fully qualified path. Additional optional keys include:

  • name - A string used in place of the folder name in the side bar.
  • file_include_patterns - A list of strings for filenames to include from the folder. Anything not matching these patterns will be excluded. This is checked before file_exclude_patterns.
  • file_exclude_patterns - A list of strings for filenames 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 - A list of strings for subfolder paths to include from the folder. Anything not matching these patterns will be excluded. This is checked before folder_exclude_patterns.
  • folder_exclude_patterns - A list of strings for subfolder paths to exclude from the folder. This is added to the global setting of the same name. This is checked after folder_include_patterns.
  • index_include_patterns - A list of strings for full file paths 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 - A list of strings for file full paths to index in the folder. This is added to the global setting of the same name. This is checked after index_include_patterns.
  • follow_symlinks - 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.

Settings

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

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

Build Systems

build_systems specifices 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.