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

# Reference State Log

> Trace and verify branch, tag, and checkpoint updates in repositories hosted on Entire with gittuf's Reference State Log.

Git tells you where a branch, tag, or Entire checkpoint points today. A force-push, replaced tag, or deleted ref can make its earlier state difficult to trace.

For repositories hosted on Entire, reference updates are recorded in the repository itself based on [gittuf's Reference State Log (RSL)](https://gittuf.dev): a cryptographically verifiable, append-only ledger. Earlier records remain traceable as refs change, giving you a history you can verify independently for audits and software supply-chain investigations. Keep using your usual Git commands and Entire records updates as you push.

The `entire-rsl` CLI plugin lets you inspect that ledger and verify refs locally. It shows the recorded push actor, time, signer, and history for branches, tags, and checkpoints.

## Before You Start

You need:

* The [Entire CLI](https://docs.entire.com/installation.md) installed.
* A local clone of a [repository hosted on Entire](https://docs.entire.com/guides/repositories/repository.md), with its Entire remote configured.
* [Entire enabled](https://docs.entire.com/quickstart.md#2-open-a-repository-and-enable-entire) and [checkpoint capture configured](https://docs.entire.com/guides/checkpoints/capture-checkpoints.md), especially if you want to follow the checkpoint steps.

New repositories that are hosted on Entire already have a gittuf policy and an initial RSL entry.

You will need to run the commands below from your repository root.

## 1. Install the Plugin

Update the plugin index, install RSL, and check its version using:

```bash theme={null}
entire plugin index update
entire plugin install rsl
entire rsl version
```

See the [plugin reference](https://docs.entire.com/cli-reference/plugin.md) for plugin management.

## 2. Fetch the Ledger

Fetch the RSL and policy from your Entire remote:

```bash theme={null}
entire rsl refresh
```

The output reports whether these refs were created, updated, or unchanged:

* `refs/gittuf/policy`
* `refs/gittuf/reference-state-log`

If your Entire remote has another name, specify it:

```bash theme={null}
entire rsl refresh entire
```

> [!NOTE]
>
> A normal Git clone does not fetch gittuf refs. `refresh` fetches the ledger and policy, but does not fetch branches, tags, or checkpoints. Use Git to fetch those refs separately when needed.

## 3. Push and Verify a Branch

Push a committed change as usual. For a branch with an upstream configured, use:

```bash theme={null}
git push
```

Entire records the reference updates on the server. If the commit has an Entire checkpoint, Entire also pushes its checkpoint ref and records an entry for it.

Pushing does not update your local ledger, you will need to refresh it and then verify your branch:

```bash theme={null}
entire rsl refresh
entire rsl verify main
```

Replace `main` with your branch name. Verification checks the ref's RSL history against the repository policy, checks its local state against the ledger, and checks the root of trust and signer. A successful result reports `verified`, `verify` exits with code `0`.

To see who pushed the branch, when, and its recorded history, use the command below:

```bash theme={null}
entire rsl branch main
```

The output includes the local tip, the tip recorded by the RSL, the signer, verification details, and a history table with entry numbers and target commit IDs.

## 4. Inspect a Checkpoint or Commit

After [capturing a checkpoint](https://docs.entire.com/guides/checkpoints/capture-checkpoints.md) and pushing it, find its ID:

```bash theme={null}
entire checkpoint list
```

Replace `<checkpoint-id>` with that ID to inspect its history and verify it:

```bash theme={null}
entire rsl checkpoint <checkpoint-id>
entire rsl verify <checkpoint-id>
```

You can also inspect the checkpoint associated with a commit through its `Entire-Checkpoint` trailer:

```bash theme={null}
entire rsl checkpoint "$(git rev-parse HEAD)"
```

To verify the commit and its checkpoint together:

```bash theme={null}
entire rsl verify "$(git rev-parse HEAD)"
```

Commit verification requires a verified branch or tag that the RSL records as containing the commit. If the commit has an `Entire-Checkpoint` trailer, the named checkpoint must verify too. A valid checkpoint alone is insufficient to verify a commit.

## Inspect Tags and Earlier Updates

For an existing tag, replace `v1.0.0` with its name:

```bash theme={null}
entire rsl refresh
entire rsl tag v1.0.0
entire rsl verify refs/tags/v1.0.0
```

The tag view includes its history and warns if the tag moved.

> [!WARNING]
>
> Recording a tag in the RSL does not guarantee it will verify. Tags must be signed by a key authorized in the repository policy. Unsigned tags, lightweight tags, and tags signed by other keys fail verification, even when the RSL entry's signature is valid.

To inspect earlier branch updates, list the entries for its full ref name:

```bash theme={null}
entire rsl log --ref refs/heads/main --limit 20
```

Inspect an individual entry by number or ID. For example, if the log includes entry `3`:

```bash theme={null}
entire rsl entry 3
```

## Understand Verification Results

| Result | Meaning | `verify` exit code |
| - | - | - |
| `verified` | The ref's history satisfies gittuf policy and all additional checks pass. | `0` |
| `failed` | Policy verification or an additional check failed. | `3` |
| `unprotected` | The RSL, policy, entries for this ref, or a covering policy rule is missing. | `3` |
| `error` | Verification could not complete. | `1` |

Exit code `2` indicates invalid command usage.

A local branch can verify while its tip check reports `behind`, if its state is covered by the verified history. This means it is verified at an earlier state; it does not mean it is up to date. Unrecorded local commits ahead of the RSL, divergent history, and states introduced by revoked entries fail verification.

The push actor and timestamp are assertions recorded by the signer. Verification relies on signatures and policy; those metadata fields do not determine whether a ref verifies.

## Refresh Before Automating Verification

Use `--fetch` to fetch the gittuf refs without needing to run **`rsl refresh`** beforehand, including when running without a terminal:

```bash theme={null}
entire rsl verify --fetch main
entire rsl verify --fetch --json main
```

All commands support `--json`. Use the `verify` command's exit code to decide whether verification passed. See the [JSON schema](https://github.com/entireio/entire-rsl/blob/main/docs/json-schema.md) for output fields, or run `entire agent-help rsl` for agent instructions.

## Troubleshooting

* **A newly pushed ref is `unprotected`:** Run `entire rsl refresh` and retry. If it remains unprotected, check the reported reason; the ref may have no entries or no covering policy rule.
* **Your branch is behind or required objects are missing:** Fetch the relevant Git refs from Entire. Update your local branch through your usual Git workflow if you need to verify the latest state. Refreshing the ledger alone does not update it.
* **Refresh reports `diverged`:** The remote gittuf ref does not descend from the local one. Refresh leaves the local ref unchanged and exits with code `1`. Investigate the mismatch before retrying verification.
* **A fetch is refused:** Review the configuration keys or remote URL named in the error. RSL fetches accept `https://` and `entire://` remotes and restrict repository-local Git configuration.

For complete command behavior and verification details, see the [entire-rsl documentation](https://github.com/entireio/entire-rsl).