version-control

version-control - remote operations through vcs.py, local operations with git

Version control here is abstracted. Everything is one of two things, and getting an operation into the right half is most of using this skill.

Remote operations — anything that crosses the network or spends a credential. These go through scripts/vcs.py, which speaks to a broker in another container. Only the broker holds the credential; nothing here does. The remote verbs are exactly these:

capabilities, identity, clone, publish, proposal create|list|view|comment|update|close|commits|acknowledge, issue create|list|view|comment|update|close, label ensure, remote-branch view|delete.

update edits a title or body and adds or removes labels; close closes; commits lists the revisions on a proposal's source branch; acknowledge reacts to a comment (its id and kind come from view --comments) so its author sees it was read — capabilities says whether this forge supports it. issue list --query <text> searches, and --without-labels skips issues carrying any of them — that is how a queue is read for unclaimed work. label ensure creates a label or updates it if it exists. identity says who this install is on the forge and, with --login, whether that login may write to the repository. remote-branch view says whether the shared repository still holds a branch and at which revision; remote-branch delete removes one only when it is spent — under platform-agent/, no open proposal on it, and its tip exactly what a merged or closed proposal this install opened from this repository carried — and only at the --revision you just read.

Local operations — everything else. clone unpacks a real working copy onto this filesystem and prints its path. Inside it, use git — git log, git show, git blame, git grep, git diff, git status, git branch, git commit, git ls-files --stage — and every read works as you expect. Read files in the working copy with cat, rg, or anything else. You do not need vcs.py for any of this and it is faster without it.

This git holds no credential and cannot reach a forge: its HTTP transport helpers are not in the image, so an https:// URL fails with 'remote-https' is not a git command, and there is no ssh client, so an ssh:// URL fails with cannot run ssh. Seeing either message means you asked it for the one thing it does not do; the answer is a vcs.py verb. There is no gh here either, for the same reason.

vcs.py also offers log, show, annotate, files, grep, diff, status, branch and commit as thin wrappers over that same local git, for when you want their JSON output. They make no network call. Use whichever you prefer; the wrapper is a convenience, not the sanctioned path.

The reason for the split is that the history is here rather than there. clone brings a repository down as a git bundle, so the full object graph — every commit, every parent, every tree entry with its mode — is on this disk. Your revisions go up the same way, as a bundle, which is why a branch of five commits arrives as five commits. Nothing that came out of the repository is ever executed beside the credential.

The script is /opt/data/profiles/platform/skills/version-control/scripts/vcs.py (scripts/vcs.py inside the skill directory). Every subcommand prints one JSON object on stdout. --repo takes owner/name or a full URL, and the broker decides which forge that is. On an install that serves more than one forge, owner/name is refused: name the repository by its URL.

Verb names are the version-control concept; the spelling you know is an alias. annotate/blame, log/history, files/manifest, grep/search, publish/push, proposal/pr/mr, create/open all work.