> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Command

> Auto-commit your agent project and optionally push to GitHub

## Overview

The `lua git` commands connect your agent project to git, so that Lua
operations automatically commit a snapshot of your project. Optionally, each
commit can also be pushed to a linked GitHub repository.

```bash theme={null}
lua git connect      # enable auto-commits for this project
lua git auth github  # link a GitHub account
lua git status       # show the current git integration state
```

<Note>
  Git integration is **opt-in** and per-project. Until you run `lua git
      connect`, Lua never touches your git repository.
</Note>

## What Auto-Commit Does

Once enabled, these commands commit your project automatically after they
succeed:

| Command                                                           | Commits | Also tags  |
| ----------------------------------------------------------------- | ------- | ---------- |
| `lua push`                                                        | ✅       | —          |
| [`lua version create`](/cli/version-command#lua-version-create)   | ✅       | `lua/v<N>` |
| [`lua version promote`](/cli/version-command#lua-version-promote) | ✅       | —          |
| [`lua version delete`](/cli/version-command#lua-version-delete)   | ✅       | —          |
| `lua pull`                                                        | ✅       | —          |

Auto-commit is non-blocking: if a commit can't be made, the Lua command still
succeeds and prints a short warning.

## Enabling Auto-Commit

<Steps>
  <Step title="Prepare your repository">
    Auto-commit needs a git repository with an identity configured:

    ```bash theme={null}
    git init
    git config user.name "Your Name"
    git config user.email "you@example.com"
    ```

    <Note>
      Lua never runs `git init` or `git config` for you — you stay in control
      of your repository.
    </Note>
  </Step>

  <Step title="Connect">
    ```bash theme={null}
    lua git connect
    ```

    This runs sanity checks (git installed, inside a repository, identity
    configured) and, on success, records the setting in `lua.skill.yaml`.
  </Step>
</Steps>

## Pushing to GitHub

To also push each auto-commit to GitHub, link a GitHub account and enable
auto-push.

<Steps>
  <Step title="Link your GitHub account">
    ```bash theme={null}
    lua git auth github
    ```

    A code is shown in your terminal; open
    [github.com/login/device](https://github.com/login/device), enter the
    code, and authorize Lua. The token is stored locally under
    `~/.lua-cli/`.

    ```text theme={null}
    Open https://github.com/login/device and enter the code: WDJB-MJHT
    ✓ Logged in to GitHub as @your-username.
    ```
  </Step>

  <Step title="Add a GitHub remote">
    Auto-push targets your `origin` remote, which must be a GitHub HTTPS URL:

    ```bash theme={null}
    git remote add origin https://github.com/<owner>/<repo>.git
    ```
  </Step>

  <Step title="Enable auto-push">
    ```bash theme={null}
    lua git connect --auto-push
    ```

    This verifies that a GitHub account is linked **and** that `origin` is a
    GitHub HTTPS remote before enabling auto-push — so you find out about a
    missing link or remote immediately, not on your next `lua push`.
  </Step>
</Steps>

After this, every auto-commit is followed by a push to your GitHub repository.
Auto-push is non-blocking: if a push fails (revoked token, network issue,
etc.), the commit is kept locally and you can run `git push` manually.

## Commands

### `lua git connect`

Enable auto-commits for the current project.

| Flag          | Description                                                                                                     |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| `--auto-push` | Also enable auto-push to the linked GitHub remote (requires `lua git auth github` and a GitHub HTTPS `origin`). |

### `lua git disconnect`

Disable auto-commits. Existing commits and tags in your repository are left
untouched.

### `lua git status`

Show the current integration state: whether it's enabled, your git identity,
and the most recent Lua-issued commit and tag.

### `lua git auth github`

Link a GitHub account using GitHub's OAuth **device flow** (enter a code at
[github.com/login/device](https://github.com/login/device)).

| Flag      | Description                                            |
| --------- | ------------------------------------------------------ |
| `--force` | Re-link without the "already linked, re-link?" prompt. |

### `lua git auth status`

Show the linked GitHub username, granted scopes, and when it was linked.

### `lua git auth disconnect`

Remove the locally stored GitHub token.

## Configuration

The `git` block in `lua.skill.yaml` is **managed by the CLI** — use the
commands above rather than editing it by hand, so the sanity checks always
run:

```yaml theme={null}
git:
  enabled: true    # set by `lua git connect`
  autoPush: true   # set by `lua git connect --auto-push`
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Git add skipped: no-repo">
    The project directory isn't a git repository yet. Run `git init` (and set
    your `user.name` / `user.email`), then `lua git connect`.
  </Accordion>

  <Accordion title="auto-push is enabled but no remote.origin.url is set">
    Add a GitHub remote: `git remote add origin
            https://github.com/<owner>/<repo>.git`. Auto-push supports GitHub HTTPS
    remotes only.
  </Accordion>

  <Accordion title="GitHub auth was revoked">
    Re-link your account with `lua git auth github`.
  </Accordion>
</AccordionGroup>