Save and compare checkpoints

Applies to SiliconForge 0.1.2 · Updated 2026-09-30. Check platform limits.

Before this task: Distinguish Git, checkpoints and candidates →

Save a named local engineering snapshot when you need a comparison point, whether or not the project uses Git.

Save sources and identify the project#

Connect the correct project, save source edits, and let file-producing tools finish before capture. Open Changes and the history navigator's Checkpoints tab. A capture reads saved files from disk; it cannot preserve an unsaved editor buffer.

A checkpoint is not a commit#

A checkpoint has a local revision identity, label, creation time, hashes of retained files and coverage information. It may carry Git provenance, but saving one does not create a Git commit, stage files, move a branch or send anything to a remote. Two snapshots can share source contents yet have different revision metadata.

Git commits identify Git trees and ancestry. Checkpoints identify scoped engineering snapshots retained by SiliconForge. Candidate revisions identify particular proposed edits. Record the identity appropriate to your review; do not relabel a checkpoint ID as a Git SHA or treat an imported comparison as historical proof of a local commit.

Worked flow: compare a parameter change#

1. With a small counter project open, choose Checkpoints. Enter Before counter width update in Checkpoint label, then choose Save.
2. Edit the counter width in the source editor, save the source, and save another checkpoint named Counter width updated.
3. Choose the earlier snapshot in Before checkpoint and the later snapshot in After checkpoint, then choose Compare.
4. Expect a retained before/after comparison. Inspect the source and parameter or port changes; an internal-width change need not alter the module's external interface.
5. Return to working files and make another edit. Reopening the same checkpoint pair should still describe the retained versions, not this new edit.

At least two different checkpoint selections are needed for a useful pair. Use Load older to retrieve earlier entries. A label helps navigation but is not a guarantee of correctness; always inspect the identities and source.

Understand what is retained#

Capture covers supported HDL inputs, recognized project/build/verification manifests and profiles, plus verification helpers in recognized locations or referenced by bounded manifests. Coverage is deliberately scoped. It does not mean that every byte under the project directory was archived.

• Git metadata, virtual environments, dependencies and generated/runtime state are outside ordinary engineering capture.
• Environment and secret-like paths or content are excluded. Do not use checkpoints as a credential vault.
• Undeclared executable helpers and unclassified manifests may be excluded or mark coverage partial.
• Symlinked engineering inputs are not followed. Inspect the diagnostic rather than assuming the linked contents were captured.

When a script, constraint or manifest matters to a conclusion, confirm it appears in the retained coverage and source. A comparison of RTL alone cannot establish that omitted build inputs are unchanged.

Recover from a failed capture#

If working files change during capture, the operation is refused rather than presenting mixed versions as one snapshot. Finish the edit or tool run, save, and retry. For unsupported or linked inputs, preserve the original layout and investigate the reported path; do not silently remove it just to get a green capture.

An older checkpoint is not an automatic restore button. Compare its retained files and prepare an explicit, reviewed change if you need to recover content. For candidate recovery use candidate review; for full-project recovery use backup and recovery.

Keep local state with the backup#

Checkpoint records, retained content and review notes live in project-local .siliconforge state. A fresh Git clone does not reproduce that state merely because the RTL files match. Back up the complete project and local state while the application and writers are closed, protect the backup, and test restoration into a separate directory. Do not copy only the SQLite database while it is in use or assume a checkpoint is an off-device backup.

Need help? Report an issue. Include your application version; never include credentials.