# Version Tracks

Tracks are named lanes for managed versions, such as `dev`, `staging`, and `prod`. A track can override base catalog entries and defaults without duplicating the full catalog.

The active track resolves from a command argument, the `--track` flag, `version.track` in `atmos.yaml`, and then `default`.

## Configuration

**File:** `atmos.yaml`

```yaml
version:
  track: prod

  dependencies:
    nginx:
      ecosystem: oci
      datasource: oci-tags
      provider: dockerhub
      package: library/nginx
      desired: "1.29.0"

  tracks:
    dev:
      defaults:
        update:
          strategy: minor
          cooldown: 0h

    prod:
      defaults:
        update:
          strategy: patch
          cooldown: 14d
      dependencies:
        nginx:
          desired: "1.28.0"
```

## Fields

- **`version.track`** — Default track name for commands and runtime version resolution.
- **`version.tracks.<name>.extends`** — Optional parent track to inherit from.
- **`version.tracks.<name>.defaults`** — Track-level defaults that override `version.defaults`.
- **`version.tracks.<name>.dependencies`** — Track-level dependency overrides merged with the base catalog.

## Examples

```shell
atmos version track list
atmos version track show prod
atmos version track update prod --group=infrastructure
```

## Try it out

### version-tracker

Copy the example into a new directory and make it your own:

```shell
atmos init examples/version-tracker
cd version-tracker
```

Compare the checked-in dev and prod tracks, then verify their pinned files. This example works offline; no cloud credentials are needed.

```shell
atmos version track list
atmos version track verify
```

- [Installation guide](/install)
- [Explore the example](/examples/version-tracker)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)