Skip to main content

!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 for field restrictions, import timing, and native tags versus quoted strings.

Usage​

  # 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​

vars:
  git_branch: !git.branch

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

Related Functions​

  • !git.sha — the current commit SHA
  • !git.ref — an immutable ref for source pinning