Documentation
¶
Overview ¶
Package git provides git-backed primitives for ctm serve: listing the YOLO checkpoint commits in a session's workdir and reverting to one of them. All operations shell out to the system `git` binary with a bounded timeout.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DiffAt ¶
DiffAt returns the unified diff (patch + commit header) for sha in workdir, produced by `git -C <workdir> show --unified=3 <sha>`.
A missing workdir or one without a `.git` entry returns an error — unlike List, which falls through to (nil, nil). The diff handler's 404 semantics are driven by the SHA-allowlist check upstream, so a bad workdir here is unexpected and should surface, not silently produce an empty string.
The caller is expected to have already validated sha through api.CheckpointsCache.IsCheckpoint — this function shells out without re-validation. Do not call with arbitrary user input.
Types ¶
type Checkpoint ¶
type Checkpoint struct {
SHA string `json:"sha"`
Subject string `json:"subject"`
TS string `json:"ts"`
Ago string `json:"ago"`
}
Checkpoint is the JSON view of a single YOLO checkpoint commit. Tags match §6 "Checkpoint JSON" exactly.
func List ¶
func List(workdir string, limit int) ([]Checkpoint, error)
List returns up to limit checkpoints from workdir, newest first. limit is capped at maxLimit. A missing workdir or one without a `.git` directory yields (nil, nil) so the caller can render an empty list without surfacing an error to the user.
type DirtyError ¶
type DirtyError struct {
Files []string
}
DirtyError is returned by Revert when the workdir has uncommitted changes and the caller did not opt in to `stashFirst`. Files holds the relative paths reported by `git status --porcelain`.
type RevertResult ¶
type RevertResult struct {
OK bool `json:"ok"`
RevertedTo string `json:"reverted_to"`
StashedAs string `json:"stashed_as,omitempty"`
}
RevertResult is the JSON payload returned by a successful revert. `StashedAs` is omitted from the output when the caller did not ask for (or did not need) a pre-revert stash.
func Revert ¶
func Revert(workdir, sha string, stashFirst bool) (RevertResult, error)
Revert resets workdir's HEAD to sha (`git reset --hard <sha>`).
If the workdir is dirty:
- !stashFirst → returns *DirtyError (no side effects).
- stashFirst → `git stash push -u -m "ctm-revert pre-<sha>"`, captures the stash commit SHA into RevertResult.StashedAs, then proceeds with the reset. If reset itself fails the stash is left in place for manual recovery — we do not auto-pop.
SECURITY CONTRACT: this function does NOT validate that sha refers to a known checkpoint. The caller (the HTTP handler in api/revert.go) is responsible for enforcing the SHA-allowlist guarantee from the spec — callers that bypass that allowlist allow arbitrary `git reset --hard` against the repo. Do not call Revert from any path that has not first cross-checked sha against the matching `/checkpoints` response.
Source Files