Stage and commit local changes

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

Before this task: Start with reproducible source and a test →

Make a local Git commit without confusing saved files, staged content and retained engineering snapshots.

To reach native whole-file Git actions directly, choose Changes → Stage & commit… (also in the application menu). This opens the Working tab without changing files. Select files and explicitly choose Stage, review the staged layer, then enter a message and choose Commit selected. Use Author… only if a local commit identity is needed.

Before you begin#

Connect the project in SiliconForge, save source-editor changes, and have Git available to the application's runtime. The project directory must be the repository root; opening a subdirectory of another repository is not equivalent. Work on a disposable project for your first run.

Git needs an author identity. Configure it in a terminal opened at the project root if it is not already configured. Replace the example values with the identity you want recorded in commits:

git config --local user.name "Your Name"
git config --local user.email "your-commit-address@example.com"

Run those commands after initializing Git. An email address in a commit is Git metadata, not a SiliconForge account requirement. Repository-local configuration avoids changing other projects.

Initialize only when there is no repository#

1. Open Changes and its History navigator.
2. In the empty History tab, choose Initialize Git history.
3. Expect a local repository on main with no commits yet. Initialization does not fabricate an initial commit or convert imported comparisons into history.

If Git metadata already exists, do not reinitialize or delete it. Confirm the opened root, then use Refresh. Existing repositories keep their own history.

Record the first-project baseline#

For the stream example, save stream_register.sv and tb.sv before opening History. If you ran simulation, you will also have generated outputs. Review the changed-path list rather than selecting everything.

1. Initialize only if this folder has no repository, then configure your repository-local author identity as above.
2. Create a plain-text .gitignore at the project root with the following entries. These patterns are appropriate for this exercise; review them against your team's own retention policy for a real project.

.siliconforge/
*.vvp
*.vcd

3. Refresh. Select only .gitignore, stream_register.sv and tb.sv, then choose Stage.
4. Inspect Staged changes. Expect these three files, not generated waveforms, simulator executables or the local application state directory.
5. Enter Record stream register and reset/stall test as the commit message, then choose Commit selected.
6. Refresh History and identify the new commit. You now have a source baseline for later review, not a remote backup or proof that every design requirement was tested.

Ignore rules do not remove a file already tracked in Git. If a generated file or sensitive material was committed earlier, stop and use your team's reviewed repository-cleanup process; adding an ignore entry does not erase published history.

Choose the comparison layer#

In the navigator's Working tab, changing the layer opens that comparison:

Working project

The selected commit against current saved files. Without an explicit selection, a Git project uses current HEAD; a project without a commit needs a previously retained native baseline. Read the displayed identities before reviewing.

Staged changes

HEAD against the Git index: all staged content, from which checked files are selected for a native commit.

Unstaged changes

The index against current files: changes not yet included in the staged version.

A file can be both staged and unstaged. Editing it after staging does not silently update its index version. Before the first commit there is no HEAD; create and inspect the initial staged content before committing. If Working project reports no earlier baseline, save a checkpoint before editing rather than treating current files as invented history.

Worked flow: commit one RTL change#

1. Start with committed rtl/top.sv and tb/top_tb.sv. Edit both, save them, and choose Refresh.
2. Inspect Working project. Check only rtl/top.sv in the changed-path list and choose Stage. This stages the entire file, not a hunk or selected diagram object.
3. Choose Staged changes. Check the intended RTL path and leave any unrelated staged paths unchecked. Inspect the staged content for each checked file. Unstaged changes should still show the testbench edit.
4. To remove the RTL file from the proposed commit, select it and choose Unstage. Its saved working content remains. Stage it again when ready.
5. Enter a descriptive Commit message, then choose Commit selected.
6. Expect a new local commit in History. The testbench remains uncommitted. No remote upload occurs.

Commit selected includes only the checked staged files. Unchecked staged files stay staged, including work prepared in another Git client. A selected file uses its staged version; later unstaged edits are not included. A selected rename includes the old and new path together.

In version 0.1.0, the older Commit action includes the entire index. Review all staged files before using that older action; the selected-file commit control described here is new in 0.1.1.

Check what the commit actually contains#

In an external terminal at the same root, these read-only commands show the latest commit and the two remaining change layers:

git log -1 --format=oneline
git show --stat --oneline HEAD
git diff --cached --name-status
git diff --name-status
git status --short

After the one-file example above, the RTL belongs to the new commit and the saved testbench edit remains unstaged. After the first baseline, the source/index should be clean; ignored outputs can still exist on disk. If the results differ from your intention, inspect them before doing another operation. A clean status is not permission to discard untracked files or a substitute for backup.

If an operation is unavailable or refused#

• Unsaved editor changes: save deliberately, then refresh. Git operations do not stand in for saving the editor.
• No staged changes or empty message: inspect the index and supply a message; an empty commit is not this workflow's purpose.
• Changed HEAD/index or active index lock: stop retrying and follow state recovery.
• Conflicts, symlinks, secret-like paths or configured clean filters: investigate the reported restriction; do not rename a credential or bypass validation simply to stage it.

Native commits deliberately do not run project hooks or signing programs. If your team requires signed commits or hook-based checks, use the approved external Git workflow described in Git interoperability.

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