# Configuration

Bivvy uses YAML configuration files to define your project setup.

## File Locations

Configuration is loaded and merged in this order (later overrides earlier):

1. Remote base configs (from `extends:`)
2. User global config (`~/.bivvy/config.yml`)
3. Project config (`.bivvy/config.yml`)
4. Split-file step definitions (`.bivvy/steps/*.yml`)
5. Workflow file for the active workflow (`.bivvy/workflows/<name>.yml`)
6. Local overrides (`.bivvy/config.local.yml`) — gitignored

On the first invocation, Bivvy creates `~/.bivvy/config.yml` automatically
if it doesn't already exist. The seeded file contains commented-out
examples of the supported `settings:` keys to make global options
discoverable. Edit it to enable machine-wide defaults, or delete it
freely — Bivvy will recreate it (with only the commented examples) on
the next run, and existing content is never overwritten.

When `bivvy run <workflow>` executes, only the workflow file matching
the requested name participates in the merge. Other workflow files in
`.bivvy/workflows/` are not parsed, so a broken sibling cannot prevent
an unrelated workflow from running. See
[Portable Workflow Files](workflows.md#portable-workflow-files) for
the full layout.

### `extends:`

The top-level `extends:` key lets a config inherit from one or more
remote base configs. Each entry is fetched, parsed, and merged before
the rest of the local file is applied — so anything you declare
locally still wins. URLs must be trusted on first use (or globally
with `--trust`).

```yaml
extends:
  - url: https://example.com/team-base.yml
```

### `template_sources:`

`template_sources:` registers additional remote registries that
contribute step templates beyond the built-in registry. Each entry
points to a URL and (optionally) configures cache behavior, priority,
timeout, and authentication. Templates from registered sources can
be referenced by name from any step's `template:` field; multiple
sources are tried in `priority` order (lower number = higher
priority). See
[Templates: Remote Sources](../templates/remote-sources.md) for the
full schema.

## Basic Structure

```yaml
app_name: "MyApp"

settings:
  defaults:
    output: verbose  # verbose | quiet | silent

steps:
  install_deps:
    command: "npm install"

workflows:
  default:
    steps: [install_deps]
```

## Variable Interpolation

Use `${VAR}` syntax to interpolate values:

```yaml
steps:
  setup:
    command: "echo Setting up ${project_name}"
```

### Resolution Priority

Variables are resolved in this order (highest to lowest):

1. Prompt values from the current run
2. Saved preferences from previous runs
3. User-defined variables (`vars:`)
4. Template inputs (the resolved `inputs:` map for the current step)
5. Environment variables
6. Built-in variables

### Built-in Variables

| Variable | Description |
|----------|-------------|
| `${project_name}` | Directory name of the project |
| `${project_root}` | Absolute path to project root |
| `${bivvy_version}` | Current Bivvy version |

### User-Defined Variables

Define reusable values — static strings or shell commands — under
the top-level `vars:` key. See [Variables](variables.md) for details.

```yaml
vars:
  version:
    command: "cat VERSION"

steps:
  tag:
    command: "git tag v${version}"
```

### Environment Variables

Environment variables are available for interpolation:

```yaml
steps:
  deploy:
    command: "deploy --env ${RAILS_ENV}"
```

### Escaping

Use `$${` to escape (outputs literal `${`):

```yaml
steps:
  example:
    command: "echo '$${NOT_INTERPOLATED}'"  # outputs: ${NOT_INTERPOLATED}
```

## Deep Merge Behavior

When multiple config files define the same key:

- **Objects**: Recursively merged (nested keys combined)
- **Arrays**: Replaced entirely (not concatenated)
- **Scalars**: Later value wins

```yaml
# .bivvy/config.yml
steps:
  deps:
    command: "yarn install"
    env:
      NODE_ENV: development

# .bivvy/config.local.yml
steps:
  deps:
    env:
      NODE_ENV: production
      # command is preserved from base
```

## Next Steps

- [Steps Configuration](steps.md)
- [Variables](variables.md)
- [Workflows Configuration](workflows.md)
- [Completed Checks](completed-checks.md)
