jvs

module

v0.4.9 Latest Latest Go to latest Published: May 12, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/agentsmith-project/jvs

Links

Open Source Insights

README ¶

JVS

Filesystem-native save points for real folders

JVS (Juicy Versioned Workspaces) saves real folders as save points. Start in an ordinary directory, save it, browse its history, open read-only views, and restore a known state when you need to recover.

mkdir myproject
cd myproject

jvs init
echo "hello" > notes.txt
jvs save -m "baseline"

echo "experiment" >> notes.txt
jvs status
jvs history

# Pick a save point ID from history.
jvs view <save> notes.txt
jvs restore <save> --discard-unsaved
jvs restore --run <restore-plan-id>

Restore is preview-first: jvs restore <save> prints a plan and the exact Run: line. Use the restore plan ID from that preview in jvs restore --run <restore-plan-id>. No folder files change until you run the plan.

Why JVS?

Need	JVS approach
Save a whole working folder	`jvs save -m "message"` captures managed files as a save point
Recover from a bad edit	`jvs history`, `jvs view`, and preview-first `jvs restore` help you choose and apply a save point
Keep real directories	A workspace is a normal folder; your tools keep using normal filesystem paths
Try another line of work	`jvs workspace new ../experiment --from <save>` creates another real folder from a save point
Diagnose trouble	`jvs doctor` and `jvs recovery` report health and interrupted restore plans

Install

Download a binary from GitHub Releases or build from source:

git clone https://github.com/agentsmith-project/jvs.git
cd jvs
make build

With Go installed, use a published version tag:

go install github.com/agentsmith-project/jvs/cmd/jvs@<VERSION>

Core Commands

Command	What it does
`jvs init [folder]`	Adopt a folder and prepare JVS control data
`jvs status`	Show the active folder, workspace, current pointer, newest save point, and unsaved changes
`jvs save -m "message"`	Create a save point for managed files in the active workspace
`jvs history`	List recent save points for the active workspace
`jvs history to <save>`	Show history ending at a save point
`jvs history from [<save>]`	Show history starting from a save point, or from the active workspace when omitted
`jvs history --path <path>`	Find save points that contain a workspace-relative path
`jvs view <save> [path]`	Open a read-only view of a save point or a path inside it
`jvs restore <save> [--path <path>]`	Preview a restore plan
`jvs restore --run <restore-plan-id>`	Execute a restore plan after JVS rechecks the folder
`jvs workspace new <folder> --from <save>`	Create another workspace folder at a path you choose
`jvs recovery status`	Show active restore recovery plans
`jvs doctor [--strict]`	Check repository health

How It Works

After jvs init, your folder stays where it is:

myproject/
├── .jvs/          # JVS control data
├── notes.txt      # your managed files
└── ...

JVS control data is not part of save points. view creates a read-only copy for inspection. restore copies managed files from a save point back into the workspace and leaves history intact.

Documentation

Start with the User Docs:

Document	Description
Quickstart	First save point and first restore
Best Practices	Daily habits for saving, previewing, restoring, workspaces, and cleanup
Concepts	Folder, workspace, save point, history, view, restore, and recovery
Command Reference	Release-facing command surface
Examples	Practical workflows
FAQ	Common questions
Troubleshooting	Common errors and fixes
Safety	Restore preview, unsaved changes, and read-only views
Recovery	Interrupted restore recovery

Contributor, architecture, and release evidence documents live under docs/.

Development

make test
make contract-check
make conformance
make lint
make release-gate

License

MIT

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
jvs command
internal
audit Package audit provides audit logging with hash chain verification.	Package audit provides audit logging with hash chain verification.
capacitygate Package capacitygate provides preflight free-space checks for operations that materialize save point payloads before mutating public state.	Package capacitygate provides preflight free-space checks for operations that materialize save point payloads before mutating public state.
cli
clonehistory Package clonehistory owns durable metadata for save points imported by repository clone.	Package clonehistory owns durable metadata for save points imported by repository clone.
compression Package compression provides compression support for JVS snapshots.	Package compression provides compression support for JVS snapshots.
diff Package diff implements snapshot differencing for JVS.	Package diff implements snapshot differencing for JVS.
doctor Package doctor provides repository health checking and repair operations.	Package doctor provides repository health checking and repair operations.
engine Package engine provides snapshot engines for copying worktree data.	Package engine provides snapshot engines for copying worktree data.
gc Package gc provides garbage collection for snapshots.	Package gc provides garbage collection for snapshots.
integrity Package integrity provides checksum and payload hash computation for snapshots.	Package integrity provides checksum and payload hash computation for snapshots.
lifecycle Package lifecycle contains durable primitives for repo and workspace lifecycle operations.	Package lifecycle contains durable primitives for repo and workspace lifecycle operations.
recovery Package recovery manages durable recovery plans for restore operations.	Package recovery manages durable recovery plans for restore operations.
recoverystate Package recoverystate classifies external restore/recovery state that can block mutations on separated-control repositories.	Package recoverystate classifies external restore/recovery state that can block mutations on separated-control repositories.
repo Package repo handles JVS repository initialization and discovery.	Package repo handles JVS repository initialization and discovery.
repoclone Package repoclone implements local JVS project cloning.	Package repoclone implements local JVS project cloning.
restore Package restore handles snapshot restore operations.	Package restore handles snapshot restore operations.
restoreplan Package restoreplan builds and persists preview plans for destructive restore operations.	Package restoreplan builds and persists preview plans for destructive restore operations.
snapshot Package snapshot handles snapshot creation, listing, and querying.	Package snapshot handles snapshot creation, listing, and querying.
snapshot/publishstate
snapshotpayload Package snapshotpayload materializes and hashes the logical user payload stored inside a snapshot directory.	Package snapshotpayload materializes and hashes the logical user payload stored inside a snapshot directory.
sourcepin Package sourcepin manages active source save point pins.	Package sourcepin manages active source save point pins.
terminal Package terminal centralizes interactive terminal detection for CLI output.	Package terminal centralizes interactive terminal detection for CLI output.
transfer
verify Package verify provides snapshot integrity verification.	Package verify provides snapshot integrity verification.
workspacepath
worktree Package worktree provides worktree management operations.	Package worktree provides worktree management operations.
pkg
color Package color provides terminal color output support for JVS.	Package color provides terminal color output support for JVS.
config Package config provides configuration file support for JVS.	Package config provides configuration file support for JVS.
errclass
fsutil Package fsutil provides filesystem utilities for atomic operations and syncing.	Package fsutil provides filesystem utilities for atomic operations and syncing.
jsonutil Package jsonutil provides deterministic JSON marshaling.	Package jsonutil provides deterministic JSON marshaling.
jvs Package jvs provides a high-level Go facade for JVS file-system version control.	Package jvs provides a high-level Go facade for JVS file-system version control.
logging Package logging provides structured logging for JVS.	Package logging provides structured logging for JVS.
model
pathutil Package pathutil provides path and name validation utilities for JVS.	Package pathutil provides path and name validation utilities for JVS.
progress Package progress provides progress reporting for long-running operations.	Package progress provides progress reporting for long-running operations.
uuidutil