Calyntro Configuration File

The config.yaml file is the central place to configure the analysis performed by Calyntro. It defines the project settings, what to include and exclude from the analysis, and how to map users to teams.

Generating a Draft Configuration

Instead of writing the configuration from scratch, you can generate a draft by scanning your repository. This will automatically populate users, common file exclusions, and suggest logical components based on your directory structure.

./scripts/generate_config.sh /path/to/your/repository -o config/config.yaml

This script runs within the Calyntro backend Docker image and does not require local Python dependencies.

Manual Configuration

If you prefer to write the file manually, follow the structure below.

Project Section

The project section contains general settings for the project and the analysis.

project:
  name: "mongodb"
  db_path: "./data_tmp"
  db_basename: "calyntro"
  repo_path: "/home/user/projects/mongo"
  branch: "master"
  analysis_since: "2025-01-01"

name: A string representing the name of the project.
db_path: The file system path where the database files will be stored.
db_basename: The base name for the generated database files (e.g., calyntro.duckdb).
repo_path: The absolute or relative path to the Git repository that you want to analyze.
branch: The specific branch of the repository to be analyzed.
analysis_since: The start date for the analysis in YYYY-MM-DD format. Commits older than this date will be ignored.

Analysis Section

The analysis section defines the scope of the code analysis, including which parts of the codebase to analyze and which to ignore.

analysis:
  components:
    - component_name: "client"
      path_prefix: "src/mongo/client/"
      display_name: "Client"
    # ... other components

  excluded_prefixes:
    - "bazel/"
    - "buildfarm/"
    # ... other prefixes

  excluded_extensions:
    - ".json"
    - ".md"
    # ... other extensions

  excluded_patterns:
    - "_test\\.(cpp|cc|py|go|java|ts|js)$"
    - "/(test|tests|spec|__tests__)/"

components: A list of objects, each representing a logical component of the software.
- component_name: A unique identifier for the component.
- path_prefix: A single directory path that identifies files belonging to this component. Use paths instead if you need to map multiple directories to one component.
- paths: A list of directory paths, all mapped to the same component. Use this when the component’s source is spread across multiple directories (e.g. src/core/ and lib/core/). Mutually exclusive with path_prefix — use one or the other per entry.
- display_name: A user-friendly name for the component that will be used in the UI.
Single-path example (classic format, still supported):
```
components:
  - component_name: "client"
    path_prefix: "src/mongo/client/"
    display_name: "Client"
```
Multi-path example (new format):
```
components:
  - component_name: "core"
    paths:
      - "src/core/"
      - "lib/core/"
    display_name: "Core"
```
File assignment uses longest-prefix matching: if a file path matches multiple components, the component with the longest matching prefix wins. If the same path_prefix appears in two different components, Calyntro raises a configuration error at sync time.

Note

Component assignments are pre-computed at import time and stored in the database. If you change the components section of your config (including switching from path_prefix to paths), run calyntro import config to re-sync the configuration and re-assign all files. Existing databases imported before version 1.4 will have unpopulated component assignments and require a full calyntro import analysis to populate them.

excluded_prefixes: A list of directory paths to be excluded from the analysis. Any file or directory starting with one of these prefixes will be ignored.
excluded_extensions: A list of file extensions to be excluded from the analysis. Files with these extensions will be ignored.
excluded_patterns: A list of regular expression patterns matched against the full file path (using re.search). Files matching any of these patterns will be excluded from import and all analysis views. This is useful for excluding test files or specific directory patterns that cannot be easily captured by prefixes or extensions alone.
excluded_authors: A list of author name patterns to exclude from all analyses. Supports glob-style wildcards (*). Use this to filter out bot accounts, CI users, or automation commits that would otherwise inflate commit counts and distort ownership metrics.

excluded_authors:
  - "*[bot]"           # matches dependabot[bot], renovate[bot], etc.
  - "GitHub Actions"   # exact name match

Wildcard rules:

* matches any sequence of characters.
Patterns are matched against the author_name field of each commit.
The filter propagates to all analyses and views — hotspots, ownership, silos, and trend data.

Note

excluded_authors filters are applied at the database view level (v_file_commits), not at parse time. This means you can add new patterns to config.yaml and re-run importer analysis without re-importing the full Git history. Only a configuration sync (importer config) followed by a view refresh is required.

Users and Teams

This part of the configuration allows you to define users and group them into teams. This is useful for attributing code changes and for team-level analysis.

users:
  - name: "jsteemann"
    aliases:
      - "jsteemann"
  # ... other users

teams:
  - name : "TeamF"
    members:
      - "jsteemann"
      - "allisoneaston"
  # ... other teams

users: A list of user objects.
- name: The canonical name of the user.
- aliases: A list of aliases (e.g., different usernames for different systems) that should be mapped to this user.
teams: A list of team objects.
- name: The name of the team.
- members: A list of user names (as defined in the users section) that belong to this team. This creates implicit team memberships that are valid from the analysis_since date onwards with no end date.

Team Memberships

The team_memberships section provides a way to track temporal membership of users in teams. This is useful for historical analysis, understanding how team composition changed over time, and correlating team changes with code metrics.

team_memberships:
  columns:
    - developer
    - team
    - valid_from
    - valid_to

  format:
    valid_from: "YYYY-MM-DD or ISO8601 datetime (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)"
    valid_to: "nullable; same format as valid_from; omit or set to null for active membership"

  entries:
    - developer: "jsteemann"
      team: "TeamF"
      valid_from: "2024-01-01"
      valid_to: null

    - developer: "allisoneaston"
      team: "TeamF"
      valid_from: "2023-06-01"
      valid_to: "2024-12-31"

team_memberships: Configuration for tracking when users belonged to teams.
- columns: Informational field documenting the expected data structure. Not used during import but helpful for understanding the schema.
- format: Format specifications and notes for the date fields used in memberships.
  - valid_from: The start date of the membership. Must be a valid date in YYYY-MM-DD format or ISO 8601 datetime format.
  - valid_to: The end date of the membership. Optional; can be omitted or set to null to indicate an ongoing membership (i.e., the user is currently a member). Must use the same format as valid_from.
- entries: A list of membership records, each specifying a time-bounded relationship between a developer and a team.
  - developer: The name or alias of the user (as defined in the users section). Aliases are automatically resolved to the corresponding user.
  - team: The name of the team (as defined in the teams section). If a team in a membership entry does not exist in the teams section, it will be created automatically.
  - valid_from: The date when the user joined the team.
  - valid_to: The date when the user left the team. Set to null or omit to indicate ongoing membership.

Important: The relationship between users and teams is defined exclusively through the team_memberships table. The teams table contains only the team identifiers and names. To query which users belong to a team, always join teams with team_memberships on the team_id field.