Work with external Git tools

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

Before this task: Understand the native local Git workflow →

Use SiliconForge for local Git review and hardware-aware comparisons while retaining your team's normal Git tools for collaboration and policy enforcement.

Agree on one repository root#

Open the directory that actually contains the project's Git metadata. In an external terminal, verify the root and current branch before changing anything:

git rev-parse --show-toplevel
git branch --show-current
git status --short
git log -1 --format=oneline

These commands inspect local state; they do not fetch or upload data. Review output before sharing it because repository paths, commit messages and author metadata can be sensitive. A Git worktree may have a .git file rather than a directory; never replace it just because it looks different.

What the native workflow does#

• Explicitly initialize a local repository without creating an automatic initial commit.
• Inspect local status, refs, commits and immediate-parent file changes.
• Stage or unstage selected whole files and commit checked staged files locally.
• Compare current files, the index, Git revisions and scoped engineering checkpoints.

Branch creation/checkout, fetch, pull, push, merge, rebase, cherry-pick, stash management and remote authentication remain external-tool operations. The local ref selector is for browsing, not checkout. A remote-tracking ref is only as current as the repository's last fetch.

Choose a tool for the task#

If you do not yet have a working copy, clone through that external client first, inspect its selected branch and then open the resulting repository root in SiliconForge. Do not put a repository URL into the project-folder picker or expect opening a folder to fetch anything.

Worked flow: switch a branch externally#

1. Save your source edits. Inspect both staged and unstaged changes and preserve unfinished work through your established Git/backup practice.
2. Close the project in SiliconForge before the external client rewrites working files. This avoids stale editor buffers or background project work racing with checkout.
3. In the repository root, use your approved Git client to fetch or switch to the intended branch. Resolve authentication, conflicts and uncommitted-work warnings there; do not force a checkout over work you need.
4. Inspect git status --short, git branch --show-current and the current commit again.
5. Reopen the project in SiliconForge, choose Refresh in History, and verify the current branch and baseline/target identities before reviewing or staging.
6. Run relevant verification for the new files and configuration. Earlier comparison notes or evidence do not automatically qualify this new revision.

A safe branch switch is a coordinated file change, not merely selecting a different label in the history browser.

Share the index deliberately#

SiliconForge and external Git clients use the same repository index. Native Stage operates on whole files. To stage selected hunks, use your external Git client's partial-staging feature, then refresh and inspect Staged changes in SiliconForge.

Do not subsequently choose native Stage for that file unless you intend to replace its partial staging with the entire saved file. Native Commit selected uses the staged blobs for checked paths, preserving unchecked index entries and later unstaged edits. The older 0.1.0 Commit action instead includes the entire staged index. Concurrent writes may be rejected by HEAD/index freshness checks; follow recovery guidance instead of defeating those checks.

Read the three states before crossing tools#

git diff --name-status
git diff --cached --name-status
git status --short

The first command reports tracked files differing from the index; the second reports index changes relative to HEAD; the third also exposes untracked paths. Inspect the actual diffs in your normal client, not only filenames. For a file staged and then edited again, both diffs can legitimately be nonempty. Save unsaved editor buffers before interpreting these commands: they describe disk and index, not unsaved text.

After a branch switch or external merge, reopen the project, refresh and rerun relevant checks. If you only staged selected hunks externally without rewriting working files, refresh and inspect both layers before deciding whether the current native whole-file operation would undo that selection.

Keep team commit policy outside the native shortcut#

Native commits intentionally do not execute repository hooks or signing programs. They produce ordinary local Git commits, but a commit created this way is not evidence that your pre-commit hook ran, that a signature exists or that required CI passed.

If team policy requires signed commits, hook-based validation or another controlled commit process, commit using that approved external workflow. Native staging also refuses external clean filters rather than launching them. Projects using Git LFS or other content filters should use the configured external Git tools for those files and inspect the resulting index and retained comparison scope carefully.

Do not weaken a team's policy to fit the native shortcut. Hardware review and Git metadata are complementary evidence, not substitutes for required checks.

What travels to another machine#

Git operations transfer the repository content you actually commit and push. SiliconForge's local checkpoints, candidate workspaces, review notes and retained evidence live separately in project-local state and do not automatically follow a clone. Do not commit .siliconforge wholesale to make it travel: it can contain proprietary source copies, private review data and large generated artifacts.

Use a reviewed project delivery/export procedure for intentional handoff and a protected full-project backup for recovery. Keep credentials, unrelated files and unnecessary local state out of shared packages. For retained history on the same project, see checkpoints; for recovery, see backup and restoration.

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