# atmos git commit

Stage paths and create a commit in a repository configured under [`git.repositories`](/cli/configuration/git), or in any local path. Commits are path-scoped and safe by default: when `--path` is provided, only those paths are staged, and the commit **fails** if unrelated dirty files exist outside the managed paths — Atmos never sweeps up files it wasn't told to commit.

## Usage

```shell
atmos git commit <name-or-path> --message=<msg> [flags]
```

With a configured repository (commit signing and author come from the repository config):

```yaml
git:
  repositories:
    flux-deploy:
      uri: https://github.com/acme/flux-deploy.git
      commit:
        signing: auto            # auto | always | never
        author:
          name: atmos[bot]
          email: atmos-bot@acme.com
```

```shell
atmos git commit flux-deploy --message="Render argocd for prod" --path=clusters/prod
```

## Examples

```shell
# Commit specific paths in a managed repository
atmos git commit flux-deploy --message="Render argocd for prod" --path=clusters/prod/argocd

# Multiple paths (repeatable or comma-separated)
atmos git commit flux-deploy --message="Update clusters" --path=clusters/prod --path=clusters/staging

# Commit in a repository at a local path
atmos git commit ./deployments --message="Update generated artifacts"

# Force GPG signing for this commit
atmos git commit flux-deploy --message="Signed release manifest" --sign

# Preview what would be staged and committed, without committing
atmos git commit flux-deploy --dry-run
```

## Behavior

- **Path-scoped staging:** with `--path`, only the listed repo-relative paths are staged. Dirty files outside the managed paths fail the commit with a list of the offending files.
- **Path validation:** every path must resolve inside the repository worktree; path traversal out of the worktree is an error.
- **Clean no-op:** when there is nothing to commit, the command exits successfully without creating an empty commit.
- **Commit author:** in environments with no `user.name`/`user.email` (typical CI runners), the repository's `commit.author` is passed per invocation without mutating Git config. Locally, your own Git config wins — when Git already resolves an author, Atmos passes nothing.
- **Signing:** the repository's `commit.signing` mode applies (`auto` by default — Git config decides); `--sign` and `--no-sign` override it per invocation.

## Arguments

- **`name-or-path` (required)**

  A repository name configured under `git.repositories`, or a filesystem path to an existing Git working tree.

## Flags

- **`--message` / `-m` (required, except with `--dry-run`)**

  Commit message.
  Environment variable: `ATMOS_GIT_MESSAGE`
- **`--path` (optional)**

  Stage only these repo-relative paths. Repeatable (`--path=a --path=b`) or comma-separated (`--path=a,b`). When omitted, all changes in the worktree are staged.
  Environment variable: `ATMOS_GIT_COMMIT_PATH`
- **`--sign` (optional)**

  Sign the commit with GPG (passes `-S` to `git commit`). Mutually exclusive with `--no-sign`.
  Environment variable: `ATMOS_GIT_SIGN`
- **`--no-sign` (optional)**

  Disable GPG signing (passes `--no-gpg-sign` to `git commit`). Mutually exclusive with `--sign`.
  Environment variable: `ATMOS_GIT_NO_SIGN`
- **`--dry-run` / `-n` (optional)**

  Report exactly what would be staged and committed without performing the commit.
  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`

## Related

- [`atmos git diff`](/cli/commands/git/diff) — preview the changes before committing
- [`atmos git push`](/cli/commands/git/push) — publish the commit to the remote
- [`kind: git` hooks](/stacks/hooks#kind-git) — commit and push automatically on lifecycle events
- [Git Configuration](/cli/configuration/git) — `commit.signing`, `commit.author`, and defaults