Skip to content

workspaces-projects.md

Latest commit

 

History

History
186 lines (128 loc) · 4.93 KB

workspaces-projects.md

File metadata and controls

186 lines (128 loc) · 4.93 KB
Raw

Workspaces and projects

kata separates repository files from issue data. Repositories and workspaces carry only enough information to resolve a project. The database lives under KATA_HOME unless KATA_DB points somewhere else.

Initialize

kata init

In a git workspace, kata init derives the project name from the git remote. Pass --project to choose the name explicitly:

kata init --project product

kata init writes .kata.toml and ensures .kata.local.toml is ignored. The local file is for per-machine settings such as a remote daemon URL.

Inside a Git repository, Kata searches for those files only as far as the nearest Git root, including when the workspace was entered through a symlink. A .kata.toml above that boundary cannot bind a nested repository or redirect kata init output outside it. Non-Git workspaces retain normal ancestor discovery.

Bind many workspaces to one project

Use the same project name in each workspace:

cd ~/code/product
kata init --project product

cd ~/code/product-worktree
kata init --project product

Both workspaces now resolve to the same project in the same local kata database. Issue short IDs, labels, links, and events are shared.

Run from outside a workspace

Use the global --workspace flag:

kata --workspace ~/code/product ready --unowned
kata --workspace ~/code/product show abc4

This is useful for scripts, cron jobs, and agents that keep their own working directory.

Project commands

List and inspect projects:

kata projects list
kata projects show product

Create a project by name without binding the current directory:

kata projects create research

projects create talks to the daemon only. It creates or returns the active project named research without writing .kata.toml, .gitignore, or agent guidance files, and without attaching a git alias. Use it for projects that do not map one-to-one to a repository workspace, then run kata init --project research later from any workspace that should resolve to the same project.

Rename a project:

kata projects rename product platform

Merge accidental duplicates:

kata projects merge old-repo new-repo --rename-target new-repo

Archive and restore a project:

kata projects remove old-lab
kata projects restore old-lab

projects remove hides the project from normal resolution but preserves events for audit. The project name stays reserved; kata init with the same name is rejected while the project is archived.

Permanently delete an archived project:

kata projects purge old-lab --force --confirm "PURGE old-lab"

projects purge is irreversible. It deletes all project data and frees the name so kata init --project old-lab works again afterward.

The project must be archived first (kata projects remove). Purging an active project fails with project_not_archived.

Two flags are required to prevent accidental data loss:

  • --force must be present.
  • --confirm must be the exact string PURGE <project> (e.g. "PURGE old-lab"). A wrong or missing value is rejected.

An optional --reason records a free-text note in the audit tombstone:

kata projects purge old-lab --force --confirm "PURGE old-lab" \
  --reason "decommissioned after team reorg"

Pass --json to receive the audit tombstone with row counts as JSON.

Federation: a project with a federation binding cannot be purged.

  • If the project is a spoke, run kata federation leave old-lab first.
  • If the project is a hub, purge is not currently supported. Hub teardown must be handled manually before the project can be purged.

!!! warning projects purge cannot be undone. Confirm you have the right project with kata projects show <project> before you kata projects remove it (projects show resolves active projects only). Once archived, the PURGE <project> confirmation string is your last check before deletion.

Detach one alias when a workspace identity was attached to the wrong project:

kata projects detach github.com/example/wrong

Use kata projects show <project> before destructive or structural project operations so you know which project and aliases are affected.

.kata.toml

The committed binding file is intentionally small:

version = 1

[project]
name = "product"

Do not put tokens or host-specific daemon URLs in .kata.toml.

.kata.local.toml

The local override file is ignored by git. A common use is routing one workspace to a remote daemon:

version = 1

[server]
url = "http://100.64.0.5:7777"

KATA_SERVER wins over .kata.local.toml when both are set.

Non-git workspaces

kata works without git. Use an explicit project name:

mkdir ~/scratch/research
cd ~/scratch/research
kata init --project research

The issue model does not depend on git commits. Git is only one way to derive a default project name and one possible source of close evidence.