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 the database, stored content, history, events, working files178and configuration. It also verifies remote history and release files by default.179Use `--offline` for a local check. The report names each check, its result,180and any part it could not verify.181Its backup command writes a consistent copy of `.koh`. Use it instead of182copying the database while Koh is using it. Keep a live `.koh` out of cloud183folder sync services; use `offer` and `steal` between machines.184185Koh does not encrypt history. Anyone who can read the database or remote can186read its saved files. Koh is intended for code and text; individual files over187512 MiB are refused.188189## Upgrade from Koh 2190191Save unfinished work with Koh 2 first. Run `koh update` in a terminal and192confirm the upgrade, then run `koh migrate` in each repository.193194Migration keeps save IDs and archives the old repository in `.koh-v2/`. It195imports the `dev` ancestry by default, falling back to `main` if `dev` has no196saves; `--lane main` selects the other line. Koh 3 refuses repository commands197in an unmigrated Koh 2 repository. See `koh man migrate` for missing file198recovery and other options.199200## Build from source201202Use the pinned compiler, `V 0.5.2 b9a2d87`. A different V revision can break203Koh, and the tests reject it.204205To compile V, install a C compiler and extract the206[V source archive](https://github.com/vlang/v/archive/b9a2d87bc6c317739113db1d96ca89a05f8903f4.tar.gz).207Copy `v.c` from the [vc bootstrap archive](https://github.com/vlang/vc/archive/9d59c143b.tar.gz)208into the extracted V directory, then run these commands there. The vc revision209is pinned too because newer bootstraps can be incompatible with this V source.210211```sh212mkdir -p .git213printf '%s\n' b9a2d87bc6c317739113db1d96ca89a05f8903f4 > .git/HEAD214cc -O2 -w -o v1 v.c -lm -lpthread215./v1 -o v2 cmd/v216./v2 -o v cmd/v217./v self218./v version219```220221The `.git/HEAD` file lets V report the pinned revision when built from an222archive. Add the directory containing the resulting `v` executable to `PATH`.223From Koh's repository root, compile Koh with:224225```sh226mkdir -p build227v -d use_bundled_libgc -o build/koh3 src/koh.v228```229230The flag builds the GC library from V's bundled source. SQLite 3.49.1 is231vendored and compiled into the executable. Every Koh build requires Boehm232garbage collection. Release builds use `sh build.sh` or233`koh build` on the target OS and CPU. Linux releases use the host C compiler234(`cc`) and static C runtime libraries. Install the toolchain's static runtime235development package if needed. Zig is not required.236Cross-compiling Koh with the pinned V disables237garbage collection, so the release script refuses it.238239## Manual and shell integration240241Run `koh man` for the full manual or `koh man <command>` for one command. The242[manual source](docs/koh3-man.txt) is also available in this repository.243244Source [shell/koh3.plugin.zsh](shell/koh3.plugin.zsh) from `~/.zshrc` for a245prompt segment and tab completion. `!` marks unsaved changes; `⚑` marks a246flagged head save. The plugin's header covers custom prompts, Starship, and247Powerlevel10k.248249Made by [Asha Software](https://asha.software/).