Skip to main content

atmos git clone

Clone a named repository configured under git.repositories, the single configured repository when only one exists, an ad hoc URI, or — in CI — the current repository as a replacement for actions/checkout. Clone is a reconcile operation: if the destination already exists, Atmos fetches and fast-forwards instead of failing, so restored CI caches and re-runs are always safe.

atmos git clone --help

Usage​

atmos git clone [name-or-uri] [flags] [-- <native git args>]

Configure repositories once in atmos.yaml, then clone them by name:

git:
  repositories:
    flux-deploy:
      uri: https://github.com/acme/flux-deploy.git
      branch: main
      clone:
        depth: 1
        single_branch: true
atmos git clone flux-deploy

Examples​

# Clone a named managed repository (destination: automatic XDG workdir)
atmos git clone flux-deploy

# Clone the single configured repository when only one exists
atmos git clone

# Clone/reconcile every repository configured under git.repositories
atmos git clone --all

# Clone an ad hoc HTTPS URI (destination: <cwd>/<repo-name>, like plain git clone)
atmos git clone https://github.com/acme/repo.git

# SCP-style URI
atmos git clone git@github.com:acme/repo.git

# go-getter style URI — same syntax used in vendoring and `source` configs
atmos git clone "git::https://github.com/acme/repo.git?ref=main&depth=1"

# Shallow, single-branch clone into an explicit destination
atmos git clone flux-deploy --depth=1 --single-branch --workdir=./deploy

# In CI (ci.enabled: true): check out the current repository into the
# working directory — replaces actions/checkout
atmos git clone

# Pass native arguments to the underlying git clone invocation
atmos git clone flux-deploy -- --no-tags

Clone Destinations​

The destination depends on the argument form:

Clone formDestination
Named managed repository (atmos git clone flux-deploy)Automatic XDG workdir ($XDG_CACHE_HOME/atmos/git/repositories/<name>), captured by the native CI cache
Single configured repository (atmos git clone with exactly one repository outside CI)Automatic XDG workdir ($XDG_CACHE_HOME/atmos/git/repositories/<name>)
No-arg CI checkout replacement (atmos git clone with ci.enabled: true and detected CI metadata)The working directory (e.g., GITHUB_WORKSPACE), exactly like actions/checkout
Ad hoc URI (atmos git clone https://...)<cwd>/<repo-name>, like plain git clone

--workdir=<path> overrides the destination in all forms.

CI Checkout Replacement​

When invoked with no argument in CI, atmos git clone infers the repository and ref from CI provider metadata. This requires:

  1. ci.enabled: true in atmos.yaml.
  2. A detected CI provider (for example, GitHub Actions).
  3. Repository metadata supplied by the provider.

Outside CI, no-arg clone reconciles the single configured repository when exactly one repository exists under git.repositories. If zero or multiple repositories are configured, pass a repository name, URI, or --all.

Fetch depth and atmos describe affected

Affected detection requires merge-base history. If atmos describe affected runs against the clone, use --depth=0 (full history) or a depth large enough to include the merge base — the same guidance that applies to fetch-depth with actions/checkout.

Arguments​

name-or-uri (optional)

A repository name configured under git.repositories, or a Git URI. Supported URI forms:

  • HTTPS: https://github.com/acme/repo.git
  • SCP-style: git@github.com:acme/repo.git
  • go-getter style: git::https://github.com/acme/repo.git?ref=main&depth=1 — the git:: prefix is stripped, ?ref= maps to the branch/ref and ?depth= to clone depth; unknown query parameters are rejected

When omitted: in CI (ci.enabled: true with a detected CI provider), performs the current-repository checkout; otherwise, reconciles the single configured repository when exactly one entry exists under git.repositories. When zero or multiple repositories are configured, pass a repository name, a URI, or --all.

Flags​

--all (optional)

Clone/reconcile every repository configured under git.repositories, concurrently. Every repository is attempted; failures are aggregated and reported at the end. Mutually exclusive with a positional argument. Environment variable: ATMOS_GIT_CLONE_ALL

--repo-uri (optional)

Remote repository URI (overrides the configured URI). Environment variable: ATMOS_GIT_REPO_URI

--branch / -b (optional)

Branch to clone. Precedence: flag > ?ref= query parameter > repository config > remote default branch. Environment variable: ATMOS_GIT_BRANCH

--remote (optional)

Remote name. Default: origin. Environment variable: ATMOS_GIT_REMOTE

--workdir (optional)

Override the destination directory for all clone forms. Environment variable: ATMOS_GIT_WORKDIR

--depth (optional)

Shallow clone depth. 0 (the default) means full history. Precedence: flag > ?depth= query parameter > clone.depth config > default. Environment variable: ATMOS_GIT_DEPTH

--filter (optional)

Partial-clone filter spec (e.g., blob:none), matching Git's own --filter flag. Environment variable: ATMOS_GIT_FILTER

--single-branch (optional)

Limit the clone to the specified branch. Environment variable: ATMOS_GIT_SINGLE_BRANCH

--submodules (optional)

Initialize submodules after clone. Off by default. Environment variable: ATMOS_GIT_SUBMODULES

--identity (optional)

Atmos Auth identity to use for this operation (global flag). Overrides the repository's auth.identity. Environment variable: ATMOS_IDENTITY

Native Git Arguments​

Arguments after -- are passed verbatim to the underlying git clone invocation. They apply only when a fresh clone runs; reconciling an existing workdir (fetch + fast-forward) does not invoke git clone.

atmos git clone flux-deploy -- --no-tags