# Teamscale IDE Configuration File Format (
This article describes the uniform configuration file format used to configure the various IDEs supported by Teamscale.
As of this writing, the IDEs already supporting the uniform
.teamscale.toml format are IntelliJ and Qt Creator.
Additionally, the format is also recognized by the command-line client for developers (
teamscale-dev) for Teamscale, which allows for a lightweight integration into other IDEs and text editors.
# File format (Version 1.0)
The Teamscale IDE configuration is determined by one or more
.teamscale.toml files stored in TOML format (opens new window).
Each file may set some properties, e.g.,
project.id, which may in turn be overridden by further, more specific
This merging of configuration files makes it possible to succinctly describe even complex setups with a handful of small
In a single
.teamscale.toml file, all properties are optional; thus, an empty file is a valid
However, some properties must be set once all applicable
.teamscale.toml files have been merged into a Teamscale IDE configuration.
# The Teamscale IDE configuration file format version of this file. version = "1.0" # Optional, default: 1.0 # Whether this is the root config file. # If true, configuration discovery stops at this file and does not continue upwards to the filesystem root. root = false # Optional, default: false [server] # The URL of the Teamscale server. # If set, it must match the URL of a server for which credentials (Username, IDE Access Key) have been configured in the respective IDE. url = "https://teamscale.io/" # Optional, but must be set in the merged configuration [project] # The Project ID (or one of its Alternative Project IDs) of the Teamscale project. # Note that the Project ID may be different from the more prominently displayed Project Name. # # If a .teamscale.toml file sets the project.id and does not set project.path # explicitly, then it implicitly sets project.path = "" (i.e., associates the # current folder with the root folder of the Teamscale project). id = "example" # Optional, but must be set in the merged configuration # The branch to use for retrieving data from the server. # # If empty or unset, the applicable branch is discovered from the VCS, with the # Teamscale default branch being a fallback. # If set and non-empty, branch auto-discovery is not used. Instead, the given branch is used branch = "main" # Optional # The code path within the Teamscale project on the server. # # Paths from parent configs will be overwritten. # Forward-slashes are used as path separators. # If empty (i.e., path = ""), the Teamscale project root is used as code path. path = "remote/path" # Optional
A minimal valid config file may look like this using the alternate TOML syntax for nested keys:
server.url = "https://teamscale.io/" project.id = "example"
Storing unrecognized properties in a
.teamscale.toml is allowed.
Hence, the following is allowed, even though the
server.contact property is not defined in version 1.0 of the file format.
[server] url = "https://teamscale.io/" contact = "mailto:email@example.com"
# Merging Strategy
The Discovery and merging strategy for
.teamscale.toml files is similar to that of the well-known
.editorconfig files (opens new window).
.teamscale.tomlinherits all properties (except for
.teamscale.tomlfiles stored in parent directories unless these are explicitly set, i.e., overridden. Thus it is possible to store the server URL and project ID only once in a
.teamscale.tomlfile placed in the repository root and set only the project path in
.teamscale.tomlfiles placed in subdirectories.
Discovery of further configuration files stops at a
.teamscale.tomlfile with the
rootproperty set to