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

# ubx diff

> Compare current compiled output against deployed state, optionally versus a git ref.

`ubx diff` compiles the XCL stack and runs a preview against the current deployed state. With `--from`, it compares the stack at a git ref to the current deployed state — useful for reviewing what a PR would change.

## Usage

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx diff [path] [flags]
```

## Flags

| Flag               | Description                                       |
| ------------------ | ------------------------------------------------- |
| `--from <git-ref>` | Git tag, branch, or commit SHA to compare against |
| `--json`           | Output raw Pulumi JSON preview                    |

## Examples

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx diff                          # diff current stack vs deployed state
ubx diff --from main              # diff main branch vs deployed state
ubx diff --from v1.2.0            # diff at tag vs deployed state
ubx diff --from abc1234           # diff at commit SHA vs deployed state
ubx diff --json                   # JSON output
```

## How `--from` works

1. ubx lists all `.xcl` files in the stack directory
2. For each file, runs `git show <ref>:<path>` to get the file at that ref
3. Writes the files to a temporary directory
4. Compiles the temporary directory and runs `pulumi preview`
5. Cleans up the temporary directory

This shows what the plan would look like if you were currently on the given git ref, compared to what's deployed.

## Without `--from`

Without `--from`, `ubx diff` is equivalent to `ubx plan` — it compiles the current source and previews against the deployed state.

## Use in GitOps

In a PR workflow:

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx diff --from main   # "what does this PR add to what's on main?"
```

Or in CI:

```yaml theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
- name: Diff vs main
  run: ubx diff --from ${{ github.base_ref }} --json > diff.json
```

## Exit codes

| Code | Meaning                      |
| ---- | ---------------------------- |
| `0`  | Diff succeeded               |
| `1`  | Compile/typecheck/diff error |