# Teamscale IDE Configuration File Format (.teamscale.toml)

This article describes the uniform configuration file format used to configure the various IDEs supported by Teamscale.

TIP

As of this writing, the only IDE already supporting the uniform .teamscale.toml format is IntelliJ.

# 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., server.url or project.id, which may in turn be overridden by further, more specific .teamscale.toml files. This merging of configuration files makes it possible to succinctly describe even complex setups.

In a single .teamscale.toml file, all properties are optional; thus, an empty file is a valid .teamscale.toml file. 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.
# Configuration discovery stops bubbling up the file tree at this file if true.

root = false # Optional, default: false

[server]

# The URL of the Teamscale server.

url = "https://teamscale.io/" # Optional, but must be set in the merged configuration

[project]

# The ID (or alias) of the Teamscale project.
#
# 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 = "admin@teamscale.io"

# Merging Strategy

Lookup and merging .teamscale.toml files is similar to the well-known .editorconfig files (opens new window).

  • A .teamscale.toml inherits all properties (except for version and root) from .teamscale.toml files 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.toml file placed in the repository root and set only the project path in .teamscale.toml files placed in subdirectories.

  • Inheritance and parent-file lookup stop at a .teamscale.toml file that specifies the property root: true.