Harbor

Harbor is a workspace-first version control prototype.

Git is excellent at tracking file history, but large multi-component workspaces often need a higher-level view of the whole project. Harbor treats the workspace itself as the main unit of state. A snapshot captures the files, component graph, contracts, and enough operation history to inspect, undo, sync, and repair the workspace later.

Harbor is ready for careful dogfooding on real projects with backups. It is not production-ready yet.

What works today

Harbor currently supports:

• local repositories with .harbor metadata,
• snapshots, logs, status, diffs, rollback, and undo,
• local branch refs,
• component manifests and dependency graphs,
• compatibility contract metadata,
• filesystem remotes with publish, fetch, sync, and clone,
• clone-time materialization filters for sparse workspaces,
• local ignore/include/exclude rules,
• object inspection,
• operation history,
• doctor and conservative repair flows.

Hub hosting lives in docs/harbor-hub.md.

Build it

You need Go 1.26.2 or newer.

go build -o bin/harbor ./cmd/harbor

Optional binaries:

go build -o bin/server ./cmd/server

Or run directly while developing:

go run ./cmd/harbor --help

Start a workspace

On the first interactive Harbor command, Harbor asks for your name and email if global identity config is missing. It saves them in harbor/config.lob under your OS user config directory and reuses that identity for snapshot authors. Non-interactive commands do not block for prompts; they keep using environment defaults.

From an existing project directory:

harbor init
harbor status
harbor snapshot "initial import"

harbor init creates .harbor. harbor snapshot records the current workspace as immutable objects and moves the current branch ref to that new workspace snapshot.

If you already have a tree on disk and want Harbor to accept it as the current state without writing a message, use:

harbor adopt

Harbor snapshots use portable defaults without extra config: regular file bytes are stored exactly as written, text files must use LF line endings, unsafe cross-platform path names are rejected, case-insensitive path collisions are rejected, symlinks are not snapshotted by default, and file permissions are normalized to ordinary file or executable file.

Daily local workflow

harbor status
harbor diff
harbor snapshot "change terrain loader"
harbor log
harbor oplog

status and diff compare the worktree to Harbor HEAD. log shows first-parent snapshot history. oplog shows operations such as snapshot, fetch, sync, rollback, undo, clone, repair, branch changes, and component updates.

If you make a mistake:

harbor rollback HEAD_OR_WORKSPACE_ID
harbor undo

rollback moves to a specific workspace snapshot. undo walks operation history and restores the previous effective workspace state for HEAD-changing operations.

Branches

harbor branch feature-a
harbor branch list
harbor branch switch feature-a
harbor branch delete feature-a

Branches are workspace refs. Switching branches requires a clean worktree and restores that branch's workspace snapshot and manifest graph.

Remotes

Filesystem remotes can publish and fetch:

harbor remote add origin /srv/harbor/my-project
harbor publish origin
harbor fetch origin
harbor sync origin

publish copies missing typed objects and updates the remote workspace ref. Incremental publish uses the current remote branch head as a boundary, so unchanged history and unchanged blobs are skipped when the remote can be read. fetch copies objects and records a local remote ref without changing your worktree. sync fetches and materializes the remote workspace into a clean local worktree.

Harbor's object compatibility contract starts at the canonical payload: object IDs are always sha256(object-type || 0x00 || canonical-payload), never hashes of compressed or stored bytes.

Clone

harbor clone /srv/harbor/my-project my-project

Clone initializes the target, restores origin, records the remote ref, materializes files, and writes a clone operation.

You can choose what materializes at clone time:

harbor clone --full SOURCE target
harbor clone --component engine SOURCE target
harbor clone --include src/ SOURCE target
harbor clone --exclude assets/raw/ SOURCE target

Those flags write local materialization rules, so the workspace stays clean even when some tracked files are intentionally absent.

Components

Harbor workspaces can describe components in root harbor.lob:

harbor component add \
  --name engine \
  --path engine \
  --source /srv/harbor/engine \
  --role library

harbor component add \
  --name game \
  --path game \
  --source /srv/harbor/game \
  --depends engine=compatible

harbor component list
harbor graph

harbor status reports pending manifest-only graph edits as manifest changed. Run harbor snapshot to record component graph changes even when tracked files are unchanged.

You can update one component from its source:

harbor update engine

Contracts

Contracts are lightweight compatibility metadata attached to components:

harbor contract add \
  --component engine \
  --name api \
  --compatibility v1

harbor contract add \
  --component game \
  --name game-api \
  --compatibility v1 \
  --requires engine=v1

harbor contract list
harbor contract validate

Current validation checks ownership, duplicate names, required components, compatible dependency edges, and required compatibility labels. Deep ABI/schema/effect validation is still future work.

Local materialization and ignore rules

harbor.lob can keep local-only noise out of status/snapshot and can control sparse materialization:

[ignore]
	patterns = "
		build/
		.tmp/
	"

[include]
	patterns = "
		engine/src/
	"

[exclude]
	patterns = "
		assets/raw/
	"

Ignore patterns affect local-only files. Include/exclude patterns affect which tracked remote paths should exist in the worktree.

Inspect and repair

harbor inspect HEAD
harbor inspect <object-id-or-prefix>
harbor doctor
harbor doctor --migrate-object-ids
harbor doctor --migrate-object-ids --repair
harbor doctor --repair

inspect prints deterministic summaries for Harbor objects. doctor checks layout, refs, configs, object hashes, object links, and operation history. Repair is conservative: it fixes cases Harbor can prove safe and refuses cases that would require guessing.

Additional docs

• VCS design: docs/harbor.md
• Hub hosting, HTTP remotes, auth, and web UI: docs/harbor-hub.md
• Lobster config format: docs/lobster.md

Suggested dogfood rules

Use Harbor on real projects, but keep it boring:

1. Keep a Git repo or backup beside the Harbor workspace.
2. Start with filesystem remotes before relying on hosted remotes.
3. Run harbor status before destructive-looking commands.
4. Prefer harbor snapshot "message" after each logical change, or let Harbor summarize the diff when the message is obvious.
5. Run harbor doctor after sync, clone, and repair experiments.

Project status

Harbor is still a prototype. Its object model, CLI, and recovery story are in place enough to test the local VCS workflow end-to-end. The next big step is real-world feedback: try it on a real workspace, write down what feels awkward, and keep an eye on correctness, performance, and recovery behavior.