verstack/docs/git-workflow.md

Git workflow

The source repository keeps the existing master branch and history. Its remote is:

ssh://git@git.sx.gy/jordan/verstack.git

The repository includes application and plugin source, dependency lockfiles, tests, synthetic demo files, service templates, and documentation. Firmware, archive data, downloads and installed tools, generated browser bundles, local configuration, credentials, and test output are excluded by .gitignore. The firmware inventory documents contain metadata, not the firmware payloads. Git is not an archive-data backup: preserve the live archive and its keys separately as described in operation and recovery.

Push with your forwarded SSH agent

Once your SSH agent is available in the server session, run from the repository:

git status --short --branch
git remote -v
git push -u origin master

SSH uses the credentials available to that session. Repository preparation does not create a key, copy credentials, change SSH configuration, or contact the remote. If authentication is unavailable, wait until your forwarded agent is available before pushing.

Existing commits and the local repository identity use Verstack Local <verstack@localhost>. To use your own identity for future commits, set it only for this repository:

git config --local user.name "Your name"
git config --local user.email "Your commit email"

Working from a fresh clone

git clone ssh://git@git.sx.gy/jordan/verstack.git
cd verstack

Follow the backend setup and Theia build instructions. Copy config.example.json to the ignored config.json, then adjust its absolute plugin paths for the clone location, Python environment, import roots, and RAM workspace. Installed tools and the live archive are not part of the clone. Service templates under deploy/ assume a checkout at ~/verstack.

For changes, stage the intended source paths and review them before committing:

git diff --check
git diff --stat
git add PATHS_TO_CHANGED_SOURCE_FILES
git diff --cached --stat
git diff --cached
git commit
git push

The lockfiles are tracked. Build output stays local. .gitattributes preserves LF line endings for text files and binary handling for images and FLIRT SIG files.