Sublime Text Projects and Build Systems: Shareable Configuration Without Shared State
Use Sublime Text projects for shared folders, editor settings, and repeatable builds while keeping personal state and shell commands out of source control.
Sublime Text’s project model is useful in a team repository because it separates configuration that can be reviewed and shared from the editor session that belongs to one person. A .sublime-project file can describe folders, selected editor settings, and project-specific build systems. Its paired .sublime-workspace file stores session data such as open files and modifications; the normal practice is to keep the project file in version control and leave the workspace file local.
That separation does not make a project file inert. A build system can launch programs, and its working directory, executable lookup, environment, and shell behavior affect what actually runs. Treat checked-in editor build configuration as code: review it, run its commands deliberately, and make the same checks succeed outside the editor and in CI.
Put shareable state in the project file
Create or edit a .sublime-project file at the repository root. Its top-level folders section describes what Sublime Text indexes, settings can hold project-level editor settings, and build_systems can define builds that are available only in that project.
{
"folders": [
{
"path": ".",
"folder_exclude_patterns": [".git", ".venv", "node_modules"],
"index_exclude_patterns": [".git", ".venv", "node_modules", "target"]
}
],
"settings": {
"tab_size": 4,
"translate_tabs_to_spaces": true
},
"build_systems": [
{
"name": "Python tests",
"selector": "source.python",
"working_dir": "$project_path",
"cmd": ["python", "-m", "pytest", "-q"]
}
]
}This example is a starting point, not a universal configuration. Use the interpreter and test command that the project documents; on some systems that may be python3, a virtual-environment executable, or a tool such as uv. The build-system selector makes the command available for Python syntax, while the explicit working directory avoids running tests relative to whichever subdirectory happens to contain the active tab.
Only editor settings are supported in a project’s settings section. User-interface and application-wide settings do not become project settings just because they are placed there. For language-specific editor behavior, Sublime Text has syntax-specific settings; for application-wide preferences, use the user’s settings file instead of committing them as if they applied to every project.
Keep project metadata separate from the workspace
The .sublime-workspace file records the current working session. It can change as files are opened, views are rearranged, or edits are made, so committing it creates noisy and user-specific diffs. Add it to the repository’s ignore rules and commit only the .sublime-project file when its settings benefit the team.
Before committing a project file, review absolute paths, excluded folders, and settings for local usernames or machine-specific directories. Prefer repository-relative folder paths. An absolute path can work on one workstation and silently point nowhere on another. If a project genuinely needs an external SDK or generated tree, document how to provision it rather than embedding one developer’s filesystem layout.
Make builds predictable and inspectable
Sublime Text build systems use JSON .sublime-build files or project-level build definitions. The built-in exec target accepts a cmd array, a working directory, environment variables, and platform-specific options. A cmd array passes the executable and arguments separately; it is generally easier to review than a single shell command string. Use shell_cmd only when shell features such as pipes or redirection are actually required, because the shell then interprets the command text.
For example, a project can expose tests and linting as separate named variants. Keep each command equivalent to a command-line workflow the team can run directly. The editor’s output panel is convenient, but it is not the source of truth for dependency installation, CI environment variables, or deployment credentials.
Treat a build system loaded from an unfamiliar repository as executable configuration. Inspect its cmd, shell_cmd, working_dir, environment entries, and any scripts it invokes before running it. A malicious command could read files available to your user or access inherited environment variables. Do not place tokens in project settings; inject credentials through a dedicated, short-lived secret mechanism in the environment that needs them.
Verify the build instead of trusting the menu
After opening the project, select the expected build system and run it against a representative file. Confirm the build output names the intended executable and working directory, that errors point to useful source locations, and that cancellation stops the child process when a task is long-running. If the build is missing from the menu, check the active syntax selector, the project file’s JSON syntax, and whether the command is defined under the current project rather than only in a different package directory.
Run the same command in the repository’s documented terminal or CI environment. Sublime Text inherits an environment from the process that launched it, which may differ from an interactive shell, especially when the application is opened from a desktop launcher. A command that depends on an uninitialized PATH, a user-specific virtual environment, or an implicit current directory can therefore work in one launch path and fail in another. Prefer an explicit project toolchain and record its setup in the repository’s normal documentation.
Use the command-line helper to open a project when testing a clean launch, and keep user workspace files out of that check. This helps distinguish a project definition problem from stale per-user session state. It does not replace running tests in CI or prove that another developer has the same installed tools.
Troubleshoot by configuration boundary
If files are missing from the sidebar or search, inspect the project’s folder paths and include/exclude patterns. If settings appear ignored, check whether the setting is an editor setting that project files can override, or a global UI/application setting that they cannot. If a build uses the wrong file, examine its syntax selector and the active build-system selection. If it works from a terminal but not from Sublime Text, compare PATH, working directory, and platform-specific overrides before changing the test command.
Projects are most maintainable when they share only a small, reviewed set of conventions: folder roots, indexing exclusions, editor settings with clear team value, and commands that are already supported by the project’s documented workflow. Leave personal session state, credentials, and workstation-specific assumptions local.
Related:
- How to Set Up a CI/CD Pipeline with GitHub Actions
- Rust in WSL: rustup Toolchains, Linux Linkers, and Target Artifacts
Sources: