Skip to main content

!git.ref

The !git.ref Atmos YAML function returns an immutable Git ref for the current HEAD. It is an alias of !git.sha — both currently resolve to the same commit SHA.

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 an immutable ref for the current HEAD.
  # If the ref cannot be resolved, it returns a default value if specified; otherwise, it returns an error.
  !git.ref <default-value>

Examples​

Use !git.ref when the intent is pinning a value to an immutable source revision (for example, a component or module version), and !git.sha when the intent is simply identifying the current commit:

vars:
  # Pin a vendored module to the current commit.
  module_version: !git.ref

  # With a fallback value when the ref cannot be resolved (e.g. not a Git repository).
  module_version_safe: !git.ref main

Related Functions​

  • !git.sha — the underlying commit SHA !git.ref resolves to
  • !git.branch — the current branch name