# !git.branch

The `!git.branch` Atmos YAML function returns the name of the current Git branch.

## Availability and evaluation

Supported locations:

- **CLI configuration** (`atmos.yaml`, `atmos.d`, and profiles): during configuration loading.
- **Resolved stack values**: after inheritance, merging, and component template processing.
- **Scaffold manifests**: during manifest loading.

Automatic evaluation requires native YAML tags from edition `2026-10-20`, including unpinned projects. Quoted function strings remain literal; earlier editions retain legacy string-form behavior.

See [YAML function scope](/functions/yaml/scope) for field restrictions, import timing, and native tags versus quoted strings.

## Usage

```yaml
  # Get the current branch name.
  # If the branch name cannot be resolved (for example, in a detached HEAD state), it returns
  # a default value if specified; otherwise, it returns an error.
  !git.branch <default-value>
```

:::info
`!git.branch` returns an error when `HEAD` is detached (for example, during a CI checkout of a specific commit
or tag) unless a default value is provided.
:::

## Examples

```yaml
vars:
  git_branch: !git.branch

  # With a fallback value for detached-HEAD CI checkouts.
  git_branch_safe: !git.branch main
```

## Related Functions

- [`!git.sha`](/functions/yaml/git.sha) — the current commit SHA
- [`!git.ref`](/functions/yaml/git.ref) — an immutable ref for source pinning