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

# Deploy Git revisions and local directories

> Deploy a branch, tag, commit, or deterministic local source archive and follow the rollout.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Queue the intended source revision and receive a verified build and active deployment result.

## Prerequisites

* An authenticated profile
* An existing StackShift project
* A connected repository for Git deployments

## Workflow

<Steps>
  <Step>
    Select the project by argument, global flag, or profile default.
  </Step>

  <Step>
    Choose a Git ref or a local directory.
  </Step>

  <Step>
    Review the local upload preview when applicable.
  </Step>

  <Step>
    Follow build output and wait for the matching active deployment.
  </Step>

  <Step>
    Use `--detach` only when another process will monitor the build.
  </Step>
</Steps>

## Deploy a Git branch, tag, or commit

`--ref` is sent unchanged to the project build contract. Use a branch, tag, or commit understood by the connected repository. When omitted, the server applies the project build default.

```bash theme={null}
stackshift deploy checkout-api --ref main
stackshift deploy checkout-api --ref v2.4.0
stackshift deploy checkout-api --ref 3a72f91
```

## Deploy a local directory

With `--local`, the CLI creates a deterministic gzip-compressed tar archive, uploads it as a source revision, and uses the build returned by that upload.

```bash theme={null}
stackshift deploy checkout-api --local .
```

## Ignore rules

The CLI applies built-in exclusions, then reads `.gitignore` and `.stackshiftignore` from the selected root. Blank lines and comments are ignored. Leading `/` is removed before matching.

* Always excluded: `.git`, nested `.git` content, `node_modules`, and `.cache`.
* Excluded by default: `.env` and `.env.*`.
* Included again by default: `.env.example` and `.env.sample`.
* Additional Docker-style patterns can be placed in `.stackshiftignore`.

## Determinism and symlink safety

* Archive paths are sorted.
* Tar and gzip timestamps are normalized to the Unix epoch.
* Ownership names and numeric user and group IDs are normalized.
* Absolute symlinks are rejected.
* Relative symlinks that resolve outside the selected root are rejected.
* Sockets, devices, and other unsupported source file types are rejected.

## Upload preview and limits

Before upload, the CLI writes the included file count, compressed bytes, and SHA-256 digest to standard error. It uses the server capability upload limit; if the server does not provide one, the archive limit defaults to 200 MiB.

The staged archive is deleted after success, failure, or cancellation.

## Follow or detach

By default, the CLI follows the build SSE stream, fetches the final build, requires a `success` status, then polls for the active deployment created from that build.

`--detach` returns as soon as the build is queued. Its result contains the project and build, but no active deployment.

```bash theme={null}
stackshift deploy checkout-api --ref main
stackshift deploy checkout-api --ref main --detach -o json
```

## Cancellation

Ctrl-C cancels archive walking and reads, upload, log streaming, and deployment polling. Cancellation returns exit code 130 and removes a staged local archive.

## Expected result

<Check>
  The command returns the project, build, final status, deployment, and URL, or a non-zero failure.
</Check>

## Common failures

<Warning>
  * The project has no connected source for the requested Git ref.
  * A local archive exceeds the server upload limit.
  * A symlink is absolute or escapes the selected source root.
  * The build finishes with a status other than `success`.
  * The matching deployment does not become active before polling ends.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Logs, remote execution, and environment variables" href="/cli/logs-exec-and-environment">
    Inspect runtime output, execute structured commands, and mutate environment variables safely.
  </Card>

  <Card title="Output, pagination, errors, and automation" href="/cli/output-and-automation">
    Select stable machine output, fetch paginated results, and handle documented exit codes.
  </Card>
</CardGroup>