store

Documentation

Overview

Package store manages ctrlz's on-disk state: the project registry and each project's bare git snapshot store. Nothing here ever writes inside a watched directory; everything lives under ~/.ctrlz.

Index

• Constants
• Variables
• func ApplyUndo(storePath, workTree, target string) error
• func DefaultIgnoreFile() (string, error)
• func Diff(storePath, workTree, a, b string) (string, error)
• func Dir() (string, error)
• func ProjectStorePath(id string) (string, error)
• func ResolvePath(path string) (string, error)
• func SnapshotCount(storePath string) (int, error)
• func StoreSize(storePath string) (int64, error)
• func TakeSnapshot(storePath, workTree, reason string) (hash string, taken bool, err error)
• func WatchLockPath(id string) (string, error)
• type ChangeSummary
• type Project
  • func Lookup(path string) (*Project, error)
  • func LookupOrCreate(path string) (*Project, bool, error)
• type Snapshot
  • func ListSnapshots(storePath string, limit int) ([]Snapshot, error)
• type UndoPlan
  • func PrepareUndo(storePath, workTree, to string) (*UndoPlan, error)

Constants

const (
	ReasonInterval = "interval"
	ReasonPreUndo  = "pre-undo"
)

Snapshot reasons, per SPEC.md section 2.

Variables

var DefaultIgnorePatterns = []string{
	".git/",
	"node_modules/",
	".venv/",
	"venv/",
	"__pycache__/",
	".next/",
	".cache/",
	"target/",
	"dist/",
	"build/",
	"vendor/",
}

DefaultIgnorePatterns is baked into the binary per SPEC.md section 4. Applied via `-c core.excludesFile=<DefaultIgnoreFile>` on every `git add -A`, in addition to (not instead of) whatever .gitignore already exists in the watched directory.

Functions

func ApplyUndo

func ApplyUndo(storePath, workTree, target string) error

ApplyUndo performs the destructive half of an undo (SPEC.md section 3, step 6): it resets workTree to exactly match target, restoring anything deleted or modified since, and removing anything added since. Both commands are required together; neither alone produces a full revert.

func DefaultIgnoreFile

func DefaultIgnoreFile() (string, error)

DefaultIgnoreFile writes the ctrlz-managed excludesFile containing DefaultIgnorePatterns and returns its path. It rewrites the file on every call so it can't drift from the patterns baked into the running binary.

func Diff

func Diff(storePath, workTree, a, b string) (string, error)

Diff returns a unified diff between snapshots a and b. If b is empty, it diffs a against the current state of workTree instead.

func Dir

func Dir() (string, error)

Dir returns ~/.ctrlz, creating it if it doesn't exist.

func ProjectStorePath

func ProjectStorePath(id string) (string, error)

ProjectStorePath returns the path to a project's bare git store.

func ResolvePath

func ResolvePath(path string) (string, error)

ResolvePath resolves path to the absolute, symlink-free form used as the registry lookup key, so the same directory reached via different symlinks still matches the same project.

func SnapshotCount

func SnapshotCount(storePath string) (int, error)

SnapshotCount returns the total number of snapshots in a project's store. A project with no snapshots yet returns 0, not an error.

func StoreSize

func StoreSize(storePath string) (int64, error)

StoreSize returns the total on-disk size, in bytes, of a project's bare git store.

func TakeSnapshot

func TakeSnapshot(storePath, workTree, reason string) (hash string, taken bool, err error)

TakeSnapshot stages every change in workTree (honoring the watched directory's own .gitignore plus DefaultIgnorePatterns) and commits it to storePath tagged with reason. If nothing changed since the last snapshot, no commit is made and taken is false, so history never fills up with empty entries.

func WatchLockPath

func WatchLockPath(id string) (string, error)

WatchLockPath returns the path to a project's watch.lock file, present only while a watch process is active for it (SPEC.md section 1).

Types

type ChangeSummary

type ChangeSummary struct {
	ToRestore int // present in the target, missing now: will be brought back
	ToRemove  int // present now, missing in the target: will be deleted
	ToModify  int // present in both, different content: will be overwritten
}

ChangeSummary counts what an undo would do to workTree, relative to the state a snapshot was taken from.

type Project

type Project struct {
	ID            string     `json:"-"`
	Path          string     `json:"path"`
	CreatedAt     time.Time  `json:"created_at"`
	LastWatchedAt *time.Time `json:"last_watched_at,omitempty"`
}

Project is a single watched directory tracked in the registry.

func Lookup

func Lookup(path string) (*Project, error)

Lookup resolves path and returns its registered project. Unlike LookupOrCreate, it never creates one: read-oriented commands (log, diff, status, undo) must fail clearly on an unregistered path rather than silently starting to track it.

func LookupOrCreate

func LookupOrCreate(path string) (*Project, bool, error)

LookupOrCreate resolves path and returns its registered project, creating a new bare store and registry entry if one doesn't already exist. The second return value reports whether a new project was created.

type Snapshot

type Snapshot struct {
	Hash      string
	Timestamp time.Time
	Reason    string
	Stat      string // one-line file-change summary, e.g. "2 files changed, 10 insertions(+), 3 deletions(-)"
}

Snapshot is one commit in a project's store.

func ListSnapshots

func ListSnapshots(storePath string, limit int) ([]Snapshot, error)

ListSnapshots returns a project's snapshots newest-first. limit <= 0 means unlimited. A project with no snapshots yet returns an empty slice, not an error.

type UndoPlan

type UndoPlan struct {
	Original     string // HEAD before anything in this undo happened
	PreUndoHash  string // hash of the pre-undo safety snapshot, "" if none was needed
	PreUndoTaken bool
	Target       string // resolved commit that will be reverted to
	Summary      ChangeSummary
}

UndoPlan is the result of preparing an undo: everything computed and committed up front, before anything destructive happens.

func PrepareUndo

func PrepareUndo(storePath, workTree, to string) (*UndoPlan, error)