Skip to main content
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): 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: 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:
See the plugin reference for plugin management.

​
2. Fetch the Ledger

Fetch the RSL and policy from your Entire remote:
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:
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:
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:
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:
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 and pushing it, find its ID:
Replace <checkpoint-id> with that ID to inspect its history and verify it:
You can also inspect the checkpoint associated with a commit through its Entire-Checkpoint trailer:
To verify the commit and its checkpoint together:
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:
The tag view includes its history and warns if the tag moved.
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:
Inspect an individual entry by number or ID. For example, if the log includes entry 3:

​
Understand Verification Results

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:
All commands support --json. Use the verify command’s exit code to decide whether verification passed. See the JSON schema 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.