Skip to main content

atmos git init

Initialize a named repository configured under git.repositories whose remote has no content yet — the inverse of atmos git clone. Atmos creates the workdir, runs git init on the configured branch, and wires the configured remote so atmos git commit and atmos git push work immediately. With --from=<uri>, the new repository is seeded from a template or migrated from an existing repository.

atmos git init --help

Usage​

atmos git init [name] [flags] [-- <native git args>]

Configure the repository once in atmos.yaml, then initialize it by name:

git:
  repositories:
    flux-deploy:
      uri: https://github.com/acme/flux-deploy.git
      branch: main
atmos git init flux-deploy

The seed source can also be configured per repository under init, so a plain atmos git init flux-deploy reproduces the same bootstrap every time:

git:
  repositories:
    flux-deploy:
      uri: https://github.com/acme/flux-deploy.git
      branch: main
      init:
        from: https://github.com/acme/flux-template.git
        keep_history: false

The --from and --keep-history flags override these configured defaults.

Examples​

# Initialize an empty repository on the configured branch with origin wired up
atmos git init flux-deploy

# Initialize the single configured repository when only one exists
atmos git init

# Seed from a template repository (fresh history: one initial commit,
# no link to the template remains)
atmos git init flux-deploy --from=https://github.com/acme/flux-template.git

# Migrate an existing repository: keep its full history and keep it pullable
# as the 'upstream' remote
atmos git init flux-deploy --from=https://github.com/acme/old-deploy.git --keep-history

# Re-running init is idempotent: reconciles an existing repo in place
atmos git init flux-deploy

# Force a clean re-create from scratch (destructive: deletes the workdir first)
atmos git init flux-deploy --force

# Preview without touching the filesystem
atmos git init flux-deploy --from=https://github.com/acme/flux-template.git --dry-run

# Pass native arguments to the underlying git invocation
atmos git init flux-deploy -- --template=/path/to/git-template

Seeding Modes​

ModeHistoryRemotes
No --fromNew, empty (no commits)origin → configured uri
--from=<uri> (default)Single fresh initial commit (Initialize from <uri>); source history discardedorigin → configured uri
--from=<uri> --keep-historySource's full history preservedorigin → configured uri, upstream → source uri (pull future template updates with git pull upstream)

In fresh mode the configured branch names the new history (git init -b <branch>); the source's default branch supplies the content. In keep-history mode the configured branch must exist in the source repository, because the history is the source's.

The initial commit created in fresh mode honors the repository's commit.signing mode and commit.author override.

Idempotent by default; --force re-creates

Re-running atmos git init is safe: when the resolved workdir is already an initialized Git repository, init reconciles it in place — it re-runs git init (idempotent) and re-points the configured remote, without re-seeding or erroring. This holds whether or not init.from is configured (the repository already exists, so there is nothing to seed).

Any other non-empty directory (not a Git repository) is refused, so init never clobbers unrelated content.

Pass --force to delete the existing workdir and re-initialize from scratch — this is destructive (uncommitted/unpushed local content is lost) and re-runs the full create or seed. Use --dry-run to preview, or atmos git clean to remove the workdir explicitly.

Arguments​

name (optional)

A repository name configured under git.repositories. The repository's uri is required — it becomes the configured remote. When omitted, Atmos initializes the single configured repository when exactly one entry exists.

Flags​

--from (optional)

Seed the new repository's content from another repository URI (a template, or a repository being migrated). Overrides the repository's configured init.from. Environment variable: ATMOS_GIT_FROM

--keep-history (optional)

Keep the seed repository's full history and keep the source reachable as the upstream remote so future updates can be pulled. Requires a seed source from either --from or the repository's configured init.from. Also settable as init.keep_history. Environment variable: ATMOS_GIT_KEEP_HISTORY

--branch / -b (optional)

Initial branch name. Precedence: flag > repository config > Git's own init.defaultBranch. Environment variable: ATMOS_GIT_BRANCH

--workdir (optional)

Override the destination directory. Default: the repository's configured workdir, or the automatic XDG workdir ($XDG_CACHE_HOME/atmos/git/repositories/<name>). Environment variable: ATMOS_GIT_WORKDIR

--force / -f (optional)

Delete the existing workdir and re-initialize from scratch. Destructive — uncommitted/unpushed local content is lost. Without --force, re-running init reconciles an existing repository in place (idempotent); use --force only when you want a clean re-create or re-seed. Environment variable: ATMOS_GIT_FORCE

--dry-run / -n (optional)

Report what would be done without initializing. Environment variable: ATMOS_GIT_DRY_RUN

--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 invocation: git init for an empty init, or the git clone of the --from repository.

# Clone the template without tags
atmos git init flux-deploy --from=https://github.com/acme/flux-template.git -- --no-tags