1# Koh23Koh is version control for a solo developer working across a few machines.4Save your project, see what changed, and bring back earlier work when you need5it. Each repository keeps its history in one SQLite file, `.koh`, with one line6of saves. Koh is written in V.78## Install910Koh runs on Apple silicon macOS and Linux on ARM64 or x86_64. New releases do11not support Intel macOS or Windows.1213```sh14curl -fsSL https://koh.asha.software/install.sh | sh15```1617The installer verifies the release checksum and offers an optional zsh plugin.18For later updates, run `koh update`. Use `koh update --check` to check without19installing.2021## Start saving2223Run these commands in your project folder:2425```sh26koh init27koh save "record the first working version"28koh status29koh view30```3132`init` creates `.koh` and a starter `.kohignore`. Check the ignore rules before33your first save. Each save snapshots every file Koh tracks, including new34files; unchanged contents are stored only once. `save` refuses when nothing35changed.3637Before a change you may want to undo, make a checkpoint:3839```sh40koh checkpoint "before changing the parser"41```4243A checkpoint records the project even when nothing changed. After editing,44`koh diff` shows the changes and `koh save "describe the result"` records them.45Commands work from subfolders too.4647`koh view` opens an interactive history browser in a terminal. Use the arrow48keys or `j` and `k` to move, `/` to search, Enter for details, and Tab to switch49between saves and checkpoints. With `--json` or when piped, it prints history.50`LOG.md` is a generated summary of the latest 20 saves.5152## Bring back earlier work5354| Command | What it does |55| --- | --- |56| `koh undo` | Restore the previous save. |57| `koh undo 3` | Step back three saves. |58| `koh load <id>` | Restore a particular save. |59| `koh load --checkpoint` | Restore the latest checkpoint. |60| `koh revert` | Discard unsaved changes, keeping them in a checkpoint first. |61| `koh peek <id>` | Unpack a save into a temporary folder for inspection. |62| `koh pluck <id>` | Apply one save's changes to the current tree as a new save. |6364Restoring earlier work adds a new save. The saves you stepped away from remain65available, so you can load them again. Koh has no branches or lanes.6667`undo`, `load`, and `pluck` require a clean working tree. Commands that rewrite68your files show a preview and ask for confirmation. Enter cancels; only `y` or69`Y` approves. Scripts must supply `--yes` to approve the action.7071## Sync your machines7273Choose an S3 bucket or a folder remote once per machine. Every repository on74that machine uses the same remote.7576For a folder, such as one on a removable drive:7778```sh79koh remote folder /Volumes/usb/koh80```8182For S3, supply the endpoint, bucket, and region. Koh asks for the access keys83and tests the connection before keeping the settings:8485```sh86koh remote s3 https://s3.fr-par.scw.cloud my-bucket fr-par87```8889If you run a [Kepr](https://kepr.uk/), `koh remote <kepr-host>` opens its sign-in90page and lets you connect with the code it supplies. `koh remote` shows the91current setting. Replacing or forgetting an existing remote requires consent.9293Once configured, saves and checkpoints offer their history automatically.94A failed transfer leaves the local save intact; run `koh offer` to retry.95On another machine, fetch a repository from outside an existing repo:9697```sh98koh steal my-project99cd my-project100```101102Inside it, `koh steal` brings in new history. If both machines changed a file,103Koh shows both versions and asks which one to keep. It resolves clashes per104file, without blending lines. The original saves remain available, and the105result names the save you can load to return to your previous state.106107Incoming changes require confirmation. For scripts, `--mine` or `--theirs`108chooses a side for every clash; `--yes` separately approves applying the changes.109110You can also fetch a public repository with `koh steal <kepr-host>/<repo>`.111That copy syncs from its public source and cannot offer back until you sign in112to that Kepr as its operator.113114## Ignore files and remove saved content115116`.kohignore` holds rules for the repository and travels with its saves.117`~/.kohignore` adds rules for every repository on this machine and stays local.118Koh also excludes its own history files, `LOG.md`, and symlinks.119120```sh121koh ignore cache/ output/ notes.txt122koh ignore --global scratch.txt123```124125`ignore` previews the exact rules and asks once for the batch. A path already126matched in the selected ignore file proposes removing its matching rules;127removing a broad rule can affect other files, which the preview explains.128Local paths are relative to the current directory. Global names and paths129match at any depth in every repository.130131Ignoring a file leaves its earlier saved versions in history.132`koh strip <path>` permanently removes a file or folder from all saves and133bans that path from future saves. It propagates the removal to the remote and other machines134as they sync. The working file stays on disk. `--save <id>` limits removal to135one save and does not ban the path.136137Strip is the exception to Koh's growing history: it cannot be undone. It138requires a terminal and each affected path typed exactly. `--yes` skips only139the yes/no question. See `koh man strip` before using it.140141## Work with coding agents142143Saves can record the agent's model and a session name:144145```sh146koh save --agent gpt-6 --session "fix parser errors" "reject incomplete input"147koh view --session "fix parser errors" --json148koh diff --session "fix parser errors"149```150151`koh undo --session` restores the state before the current session. Use the152actual model identifier and keep one session name for related work.153154Commands that print data support `--json`. Koh refuses when a required prompt155cannot be answered, so unattended commands never wait for input. Exit codes156are `0` for success, `1` for refusal or failure, and `2` for bad usage.157158## Build projects and publish releases159160A project's `koh.build` file names its build command, output, and platforms.161`koh build` runs it for the current machine without uploading or installing162anything. The toolchain must already be on `PATH`.163164`koh offer --builds` builds every configured platform and publishes the165artifacts as a release. It requires a saved tree and a version in the project's166own files, such as `VERSION`, `v.mod`, or `package.json`. Ordinary saves never167publish builds. See the [specification](docs/koh-kepr-3-master-spec.md) for the168file format, and `koh man build` or `koh man offer` for command options.169170## Back up a repository171172```sh173koh doctor174koh doctor --backup /path/to/new-backup.koh175```176177`doctor` checks database integrity, object hashes, and saved file references.178Its backup command writes a consistent copy of `.koh`. Use it instead of179copying the database while Koh is using it. Keep a live `.koh` out of cloud180folder sync services; use `offer` and `steal` between machines.181182Koh does not encrypt history. Anyone who can read the database or remote can183read its saved files. Koh is intended for code and text; individual files over184512 MiB are refused.185186## Upgrade from Koh 2187188Save unfinished work with Koh 2 first. Run `koh update` in a terminal and189confirm the upgrade, then run `koh migrate` in each repository.190191Migration keeps save IDs and archives the old repository in `.koh-v2/`. It192imports the `dev` ancestry by default, falling back to `main` if `dev` has no193saves; `--lane main` selects the other line. Koh 3 refuses repository commands194in an unmigrated Koh 2 repository. See `koh man migrate` for missing file195recovery and other options.196197## Build from source198199Use the pinned compiler, `V 0.5.2 b9a2d87`. A different V revision can break200Koh, and the tests reject it. The [agent guide](AGENTS.md) covers installing201the pin and preparing a Linux build environment.202203```sh204mkdir -p build205v -o build/koh3 src/koh.v206v test src/207v test tests/208v fmt -verify src/ tests/209```210211SQLite 3.49.1 is vendored and compiled into the executable. Every Koh build212requires Boehm garbage collection. Release builds use `sh build.sh` or213`koh build` on the target OS and CPU; Linux releases also need Zig on `PATH`214for the static musl toolchain. Cross-compiling Koh with the pinned V disables215garbage collection, so the release script refuses it.216217Source lives under `src/`, grouped by responsibility. `tests/` holds CLI and218library checks; `vendor/` holds SQLite and C shims. The [master219specification](docs/koh-kepr-3-master-spec.md) records the storage, history,220sync, and release contracts. Changes here follow [Strict Koh221Discipline](AGENTS.md): checkpoint first, verify the build and tests, and save222one coherent result at a time.223224## Manual and shell integration225226Run `koh man` for the full manual or `koh man <command>` for one command. The227[manual source](docs/koh3-man.txt) is also available in this repository.228229Source [shell/koh3.plugin.zsh](shell/koh3.plugin.zsh) from `~/.zshrc` for a230prompt segment and tab completion. `!` marks unsaved changes; `⚑` marks a231flagged head save. The plugin's header covers custom prompts, Starship, and232Powerlevel10k.233234Made by [Asha Software](https://asha.software/).