Compatibility

Support matrix, upgrade rules, and versioning contract for unch.

Module path compatibility

• Canonical module path: github.com/uchebnick/unch
• Canonical source install path: github.com/uchebnick/unch/cmd/unch@latest
• Older unch-searcher references should be treated as legacy

CLI compatibility

• Existing commands and flags are expected to stay stable across patch releases
• Breaking CLI changes should only happen in minor releases
• New flags should be additive

Manifest compatibility

• Local repository state lives in .semsearch/manifest.json
• Manifest compatibility is governed by schema_version
• version is the logical publication or generation number of indexed repo state
• Remote binding metadata also lives in the manifest, which means remote configuration is checkout-local state

Index compatibility

• index.db is a rebuildable cache artifact, not a durable user database
• Active index state is provider-scoped and model-scoped
• When the current binary cannot use a database layout, the fix is to rebuild the index

Remote and CI compatibility

• Remote sync trusts published state only when it is compatible with the local binary
• If a published remote index uses an older incompatible schema, local search should keep using a compatible local cache when available
• Repositories that use remote indexing must rerun .github/workflows/unch-index.yml after incompatible indexing releases
• A local reindex detaches remote binding and returns the manifest to local-only mode until the checkout is rebound

Support matrix

Area	Status	Notes
Go indexing	Supported	Tree-sitter-based symbol extraction
Rust indexing	Supported	Tree-sitter-based symbol extraction
TypeScript indexing	Supported	Tree-sitter-based symbol extraction
JavaScript indexing	Supported	Tree-sitter-based symbol extraction
Python indexing	Supported	Tree-sitter-based symbol extraction
Other languages	Limited	Legacy prefix fallback only
Search modes	Supported	auto, semantic, lexical
Homebrew install	Supported	macOS-first polished install path
go install	Supported	CLI package path is github.com/uchebnick/unch/cmd/unch; requires a cgo-capable Go toolchain
install.sh	Supported	Uses release assets on macOS and Linux by default, verifies downloads against published checksums, and falls back to go install only when no matching archive is available
install/install.ps1	Supported	Uses release assets on Windows by default, verifies downloads against published checksums, and falls back to go install only when no matching archive is available
Darwin release binaries	Supported	arm64 and x86_64
Linux release binaries	Supported	arm64 and x86_64
Windows release binaries	Supported	arm64 and x86_64
Remote indexing	Supported	GitHub Actions remote index workflow (unch-index.yml)

Published release binaries and CI builds on macOS, Linux, and Windows arm64/x86_64 use the full cgo-backed Tree-sitter and SQLite stack. Manual Windows builds without cgo remain a fallback path and should not be treated as identical to the published binaries. go install is smoke-tested in CI in the official Debian-based Go container image; install.sh is smoke-tested on Ubuntu, Debian, Arch, and NixOS-like Linux environments; install/install.ps1 is smoke-tested on Windows arm64 and x86_64.

CLI stability

Existing commands and flags are expected to stay stable across patch releases.

Breaking CLI changes should only happen in minor releases, and new flags should be additive.

Manifest and index state

Local repository state lives in .semsearch/manifest.json.

schema_version governs manifest compatibility, while index.db remains a rebuildable cache artifact rather than a durable user database.

Remote and CI state

Remote sync only trusts published state when it is compatible with the local binary.

If a published remote index uses an older incompatible schema, local search should keep using a compatible local cache when available.

Practical upgrade rule

If unch upgrades and local search breaks, rerun unch index.

If remote sync reports an incompatible published schema, rerun .github/workflows/unch-index.yml.

Practical upgrade rules

• If unch upgrades and local search breaks, rerun unch index
• If remote sync reports an incompatible published schema, rerun the repository remote index workflow
• If you automate installation from source, use go install github.com/uchebnick/unch/cmd/unch@latest