# tether

> Version control (fingerprints, pins, and forks) for heterogeneous datasets: files and object stores, Icechunk, Lance, Delta, git, and -- experimental -- Neon, Iceberg, DuckLake, Dolt

## Docs

### API Reference

#### Repository
> The engine and the results it returns.

- [Repo](https://rosebud-biosciences.github.io/tether/reference/Repo.html): A tether dataset: manifests in a VCS working tree plus the systems they name
- [StatusReport](https://rosebud-biosciences.github.io/tether/reference/StatusReport.html): Result of `Repo.status`
- [ObjectStatus](https://rosebud-biosciences.github.io/tether/reference/ObjectStatus.html): One object's classification in a `StatusReport`
- [VcsDrift](https://rosebud-biosciences.github.io/tether/reference/VcsDrift.html): A dataset commit that is gone from VCS history without tether knowing
- [CommitResult](https://rosebud-biosciences.github.io/tether/reference/CommitResult.html): Result of `Repo.commit`
- [GcReport](https://rosebud-biosciences.github.io/tether/reference/GcReport.html): Result of `Repo.gc`
- [AbandonReport](https://rosebud-biosciences.github.io/tether/reference/AbandonReport.html): What `Repo.abandon` did
- [DropReport](https://rosebud-biosciences.github.io/tether/reference/DropReport.html): What `Repo.drop` did: a bookmark, its commits, and its store leftovers,
- [ForgetWorkspaceReport](https://rosebud-biosciences.github.io/tether/reference/ForgetWorkspaceReport.html): What `Repo.apply_forget_workspace` did
- [PullReport](https://rosebud-biosciences.github.io/tether/reference/PullReport.html): What `pull` did: the fetched heads of a bookmark's branches, committed
- [SetReport](https://rosebud-biosciences.github.io/tether/reference/SetReport.html): What `set` changed per object
- [PromoteReport](https://rosebud-biosciences.github.io/tether/reference/PromoteReport.html): Result of `Repo.apply_promote`
- [UndoReport](https://rosebud-biosciences.github.io/tether/reference/UndoReport.html): What `Repo.undo` reversed, could not reverse, and left alone
- [RepairReport](https://rosebud-biosciences.github.io/tether/reference/RepairReport.html): What `Repo.repair` rebuilt
- [RecoverReport](https://rosebud-biosciences.github.io/tether/reference/RecoverReport.html): What `Repo.recover_report` found: tether's refs in each object's store,
- [RecoverStep](https://rosebud-biosciences.github.io/tether/reference/RecoverStep.html): One step of a `RecoverReport`: a command to run, or none, and a note
- [RecoveredObject](https://rosebud-biosciences.github.io/tether/reference/RecoveredObject.html): One object's row in a `RecoverReport`
- [RecoveredRefs](https://rosebud-biosciences.github.io/tether/reference/RecoveredRefs.html): The refs a store holds under one dataset id (see `RecoverReport`)
- [upgrade.UpgradeReport](https://rosebud-biosciences.github.io/tether/reference/upgrade.UpgradeReport.html)
- [DiffEntry](https://rosebud-biosciences.github.io/tether/reference/DiffEntry.html): One object's row in `Repo.diff`
- [TETHER_REV_ENV](https://rosebud-biosciences.github.io/tether/reference/TETHER_REV_ENV.html): str(object='') -> str

#### Operation log
> What tether did to the stores, per workspace; what undo works from.

- [OpEntry](https://rosebud-biosciences.github.io/tether/reference/OpEntry.html): One applied operation
- [oplog.OpEntry](https://rosebud-biosciences.github.io/tether/reference/oplog.OpEntry.html)
- [oplog.TouchedStore](https://rosebud-biosciences.github.io/tether/reference/oplog.TouchedStore.html)
- [oplog.tether_path](https://rosebud-biosciences.github.io/tether/reference/oplog.tether_path.html)
- [oplog.new_op_id](https://rosebud-biosciences.github.io/tether/reference/oplog.new_op_id.html)
- [oplog.ops_path](https://rosebud-biosciences.github.io/tether/reference/oplog.ops_path.html)
- [oplog.report_dict](https://rosebud-biosciences.github.io/tether/reference/oplog.report_dict.html)
- [oplog.read_ops](https://rosebud-biosciences.github.io/tether/reference/oplog.read_ops.html)
- [oplog.read_jsonl](https://rosebud-biosciences.github.io/tether/reference/oplog.read_jsonl.html)
- [oplog.append_index_entry](https://rosebud-biosciences.github.io/tether/reference/oplog.append_index_entry.html)
- [oplog.remove_index_entry](https://rosebud-biosciences.github.io/tether/reference/oplog.remove_index_entry.html)
- [oplog.touched_path](https://rosebud-biosciences.github.io/tether/reference/oplog.touched_path.html)
- [oplog.append_touched](https://rosebud-biosciences.github.io/tether/reference/oplog.append_touched.html)
- [oplog.read_touched](https://rosebud-biosciences.github.io/tether/reference/oplog.read_touched.html)
- [oplog.remove_touched](https://rosebud-biosciences.github.io/tether/reference/oplog.remove_touched.html)
- [oplog.pinned_path](https://rosebud-biosciences.github.io/tether/reference/oplog.pinned_path.html)
- [oplog.read_pinned](https://rosebud-biosciences.github.io/tether/reference/oplog.read_pinned.html)
- [oplog.append_pinned](https://rosebud-biosciences.github.io/tether/reference/oplog.append_pinned.html)
- [oplog.remove_pinned](https://rosebud-biosciences.github.io/tether/reference/oplog.remove_pinned.html)
- [oplog.mark_progress](https://rosebud-biosciences.github.io/tether/reference/oplog.mark_progress.html)
- [oplog.append_op](https://rosebud-biosciences.github.io/tether/reference/oplog.append_op.html)
- [oplog.mark_done](https://rosebud-biosciences.github.io/tether/reference/oplog.mark_done.html)
- [oplog.mark_undone](https://rosebud-biosciences.github.io/tether/reference/oplog.mark_undone.html)
- [oplog.OPS_FILENAME](https://rosebud-biosciences.github.io/tether/reference/oplog.OPS_FILENAME.html)
- [oplog.TOUCHED_FILENAME](https://rosebud-biosciences.github.io/tether/reference/oplog.TOUCHED_FILENAME.html)
- [oplog.PINNED_FILENAME](https://rosebud-biosciences.github.io/tether/reference/oplog.PINNED_FILENAME.html)

#### OpEntry Methods
> Methods for the OpEntry class

- [OpEntry.now](https://rosebud-biosciences.github.io/tether/reference/OpEntry.now.html)
- [OpEntry.incomplete](https://rosebud-biosciences.github.io/tether/reference/OpEntry.incomplete.html)
- [OpEntry.to_dict](https://rosebud-biosciences.github.io/tether/reference/OpEntry.to_dict.html)
- [OpEntry.from_dict](https://rosebud-biosciences.github.io/tether/reference/OpEntry.from_dict.html)
- [OpEntry.undoable](https://rosebud-biosciences.github.io/tether/reference/OpEntry.undoable.html)
- [OpEntry.summary](https://rosebud-biosciences.github.io/tether/reference/OpEntry.summary.html)

#### Migrations
> The one composed migration behind `tether upgrade`, from any 0.1.0 alpha format to the current one. Ships with the betas and is removed at 0.1.0.

- [upgrade.Repo](https://rosebud-biosciences.github.io/tether/reference/upgrade.Repo.html)
- [upgrade.Plan](https://rosebud-biosciences.github.io/tether/reference/upgrade.Plan.html)
- [upgrade.Migration](https://rosebud-biosciences.github.io/tether/reference/upgrade.Migration.html)
- [upgrade.UpgradeReport](https://rosebud-biosciences.github.io/tether/reference/upgrade.UpgradeReport.html)
- [upgrade.TetherError](https://rosebud-biosciences.github.io/tether/reference/upgrade.TetherError.html)
- [upgrade.ensure_ignored](https://rosebud-biosciences.github.io/tether/reference/upgrade.ensure_ignored.html)
- [upgrade.write_config](https://rosebud-biosciences.github.io/tether/reference/upgrade.write_config.html)
- [upgrade.report_dict](https://rosebud-biosciences.github.io/tether/reference/upgrade.report_dict.html)
- [upgrade.pending](https://rosebud-biosciences.github.io/tether/reference/upgrade.pending.html)
- [upgrade.outdated_message](https://rosebud-biosciences.github.io/tether/reference/upgrade.outdated_message.html)
- [upgrade.plan_upgrade](https://rosebud-biosciences.github.io/tether/reference/upgrade.plan_upgrade.html)
- [upgrade.apply_upgrade](https://rosebud-biosciences.github.io/tether/reference/upgrade.apply_upgrade.html)
- [upgrade.upgrade](https://rosebud-biosciences.github.io/tether/reference/upgrade.upgrade.html)
- [upgrade.CONFIG_VERSION](https://rosebud-biosciences.github.io/tether/reference/upgrade.CONFIG_VERSION.html)
- [upgrade.MIGRATIONS](https://rosebud-biosciences.github.io/tether/reference/upgrade.MIGRATIONS.html)
- [upgrade.LAST_BETA_WITH_UPGRADE](https://rosebud-biosciences.github.io/tether/reference/upgrade.LAST_BETA_WITH_UPGRADE.html)

#### Plans
> What a store-writing command would do, as data. `Repo.plan_*` returns a `Plan`; `Repo.apply_*` executes one after re-checking the world matches.

- [Plan](https://rosebud-biosciences.github.io/tether/reference/Plan.html): The actions a command would perform, plus the inputs they depend on
- [Precondition](https://rosebud-biosciences.github.io/tether/reference/Precondition.html): One thing that must still hold when a plan is applied
- [Action](https://rosebud-biosciences.github.io/tether/reference/Action.html): One store-writing step in a `Plan`

#### Plan Methods
> Methods for the Plan class

- [Plan.writes](https://rosebud-biosciences.github.io/tether/reference/Plan.writes.html)
- [Plan.is_empty](https://rosebud-biosciences.github.io/tether/reference/Plan.is_empty.html)
- [Plan.require](https://rosebud-biosciences.github.io/tether/reference/Plan.require.html)
- [Plan.digest](https://rosebud-biosciences.github.io/tether/reference/Plan.digest.html)
- [Plan.to_dict](https://rosebud-biosciences.github.io/tether/reference/Plan.to_dict.html)
- [Plan.to_json](https://rosebud-biosciences.github.io/tether/reference/Plan.to_json.html)
- [Plan.from_dict](https://rosebud-biosciences.github.io/tether/reference/Plan.from_dict.html)
- [Plan.edited](https://rosebud-biosciences.github.io/tether/reference/Plan.edited.html)
- [Plan.from_json](https://rosebud-biosciences.github.io/tether/reference/Plan.from_json.html)
- [Plan.missing_preconditions](https://rosebud-biosciences.github.io/tether/reference/Plan.missing_preconditions.html)
- [Plan.render](https://rosebud-biosciences.github.io/tether/reference/Plan.render.html)

#### Manifest model
> What is committed to the VCS (`tether.toml`, `.tether/objects/*.toml`) and kept untracked (`.tether/workspace.toml`), plus the hashing and naming helpers behind pin ids and refs.

- [RepoConfig](https://rosebud-biosciences.github.io/tether/reference/RepoConfig.html): Committed repository configuration
- [Policy](https://rosebud-biosciences.github.io/tether/reference/Policy.html): Per-object behavioral knobs
- [Pin](https://rosebud-biosciences.github.io/tether/reference/Pin.html): A durable native reference created for a committed state
- [ObjectManifest](https://rosebud-biosciences.github.io/tether/reference/ObjectManifest.html): The committed record for one object
- [WorkspaceState](https://rosebud-biosciences.github.io/tether/reference/WorkspaceState.html): Untracked per-workspace working state
- [compute_pin_id](https://rosebud-biosciences.github.io/tether/reference/compute_pin_id.html): Content-address a pin: ``<dataset8>.<hash16>``
- [ref_for_pin](https://rosebud-biosciences.github.io/tether/reference/ref_for_pin.html): Native reference name for a pin id (dot-delimited; no ``/``)
- [working_ref_name](https://rosebud-biosciences.github.io/tether/reference/working_ref_name.html): The store branch that stands for a dataset bookmark
- [working_ref_bookmark](https://rosebud-biosciences.github.io/tether/reference/working_ref_bookmark.html): The bookmark slug a working ref stands for; ``None`` for legacy
- [working_ref_workspace](https://rosebud-biosciences.github.io/tether/reference/working_ref_workspace.html): The 8-char workspace id in a *legacy* working ref name (before
- [listing_name](https://rosebud-biosciences.github.io/tether/reference/listing_name.html): Content-addressed file name for a state's listing
- [manifest_hash](https://rosebud-biosciences.github.io/tether/reference/manifest_hash.html): Hash the full committed object set (order-independent)

#### Handles
> Typed native handles returned by `Repo.open`.

- [handles.Handle](https://rosebud-biosciences.github.io/tether/reference/handles.Handle.html)
- [handles.FileHandle](https://rosebud-biosciences.github.io/tether/reference/handles.FileHandle.html)
- [handles.IcechunkHandle](https://rosebud-biosciences.github.io/tether/reference/handles.IcechunkHandle.html)
- [handles.NeonHandle](https://rosebud-biosciences.github.io/tether/reference/handles.NeonHandle.html)
- [handles.GitHandle](https://rosebud-biosciences.github.io/tether/reference/handles.GitHandle.html)
- [handles.IcebergHandle](https://rosebud-biosciences.github.io/tether/reference/handles.IcebergHandle.html)
- [handles.DeltaHandle](https://rosebud-biosciences.github.io/tether/reference/handles.DeltaHandle.html)
- [handles.LanceHandle](https://rosebud-biosciences.github.io/tether/reference/handles.LanceHandle.html)
- [handles.DuckLakeHandle](https://rosebud-biosciences.github.io/tether/reference/handles.DuckLakeHandle.html)
- [handles.DoltHandle](https://rosebud-biosciences.github.io/tether/reference/handles.DoltHandle.html)
- [handles.MemoryHandle](https://rosebud-biosciences.github.io/tether/reference/handles.MemoryHandle.html)
- [handles.redact_url](https://rosebud-biosciences.github.io/tether/reference/handles.redact_url.html)

#### Backend protocol
> Implement `ObjectBackend` and register it to add a system; capability flags decide which commands apply.

- [backends.ChangeEntry](https://rosebud-biosciences.github.io/tether/reference/backends.ChangeEntry.html)
- [backends.HistoryEntry](https://rosebud-biosciences.github.io/tether/reference/backends.HistoryEntry.html)
- [backends.ObjectDiff](https://rosebud-biosciences.github.io/tether/reference/backends.ObjectDiff.html)
- [backends.VerifyReport](https://rosebud-biosciences.github.io/tether/reference/backends.VerifyReport.html)
- [backends.ObjectBackend](https://rosebud-biosciences.github.io/tether/reference/backends.ObjectBackend.html)
- [backends.Capability](https://rosebud-biosciences.github.io/tether/reference/backends.Capability.html)
- [backends.Tier](https://rosebud-biosciences.github.io/tether/reference/backends.Tier.html)
- [backends.VerifyStatus](https://rosebud-biosciences.github.io/tether/reference/backends.VerifyStatus.html)
- [backends.base_at](https://rosebud-biosciences.github.io/tether/reference/backends.base_at.html)
- [backends.build_backend](https://rosebud-biosciences.github.io/tether/reference/backends.build_backend.html)
- [backends.content_state](https://rosebud-biosciences.github.io/tether/reference/backends.content_state.html)
- [backends.effective_capabilities](https://rosebud-biosciences.github.io/tether/reference/backends.effective_capabilities.html)
- [backends.known_kinds](https://rosebud-biosciences.github.io/tether/reference/backends.known_kinds.html)
- [backends.register_backend](https://rosebud-biosciences.github.io/tether/reference/backends.register_backend.html)
- [backends.tier_of](https://rosebud-biosciences.github.io/tether/reference/backends.tier_of.html)
- [backends.MAX_DIFF_ENTRIES](https://rosebud-biosciences.github.io/tether/reference/backends.MAX_DIFF_ENTRIES.html)
- [backends.Listings](https://rosebud-biosciences.github.io/tether/reference/backends.Listings.html)

#### Conformance suite
> Capability-parametrized checks for backend authors.

- [testing.BackendError](https://rosebud-biosciences.github.io/tether/reference/testing.BackendError.html)
- [testing.RefMovedError](https://rosebud-biosciences.github.io/tether/reference/testing.RefMovedError.html)
- [testing.ObjectDiff](https://rosebud-biosciences.github.io/tether/reference/testing.ObjectDiff.html)
- [testing.Handle](https://rosebud-biosciences.github.io/tether/reference/testing.Handle.html)
- [testing.Pin](https://rosebud-biosciences.github.io/tether/reference/testing.Pin.html)
- [testing.Policy](https://rosebud-biosciences.github.io/tether/reference/testing.Policy.html)
- [testing.ObjectBackend](https://rosebud-biosciences.github.io/tether/reference/testing.ObjectBackend.html)
- [testing.BackendHarness](https://rosebud-biosciences.github.io/tether/reference/testing.BackendHarness.html)
- [testing.Capability](https://rosebud-biosciences.github.io/tether/reference/testing.Capability.html)
- [testing.VerifyStatus](https://rosebud-biosciences.github.io/tether/reference/testing.VerifyStatus.html)
- [testing.accepts_expected](https://rosebud-biosciences.github.io/tether/reference/testing.accepts_expected.html)
- [testing.content_state](https://rosebud-biosciences.github.io/tether/reference/testing.content_state.html)
- [testing.effective_capabilities](https://rosebud-biosciences.github.io/tether/reference/testing.effective_capabilities.html)
- [testing.compute_pin_id](https://rosebud-biosciences.github.io/tether/reference/testing.compute_pin_id.html)
- [testing.ref_for_pin](https://rosebud-biosciences.github.io/tether/reference/testing.ref_for_pin.html)
- [testing.working_ref_name](https://rosebud-biosciences.github.io/tether/reference/testing.working_ref_name.html)
- [testing.run_conformance](https://rosebud-biosciences.github.io/tether/reference/testing.run_conformance.html)
- [testing.ABSENT](https://rosebud-biosciences.github.io/tether/reference/testing.ABSENT.html)
- [testing.Locator](https://rosebud-biosciences.github.io/tether/reference/testing.Locator.html)
- [testing.CONFORMANCE_DATASET](https://rosebud-biosciences.github.io/tether/reference/testing.CONFORMANCE_DATASET.html)
- [testing.RACERS](https://rosebud-biosciences.github.io/tether/reference/testing.RACERS.html)

#### Registries (experimental)
> Export tables (`ExportBundle`, `TABLES`), Postgres publishing, and the canonical import columns / sources for `import`. Lives under `tether.experimental.registry`; import the public names from `tether`.

- [experimental.registry](https://rosebud-biosciences.github.io/tether/reference/experimental.registry.html)
- [experimental.registry.ImportReport](https://rosebud-biosciences.github.io/tether/reference/experimental.registry.ImportReport.html)

#### Store lifecycle (experimental)
> `add --create` / `Repo.create` make a store tether owns; `gc --delete-stores` removes it once nothing references it. The created- and touched-store indexes, the planning rules, and the graduation criteria live in `tether.experimental.lifecycle`.

- [experimental.lifecycle](https://rosebud-biosciences.github.io/tether/reference/experimental.lifecycle.html)

#### VCS adapters
> How tether reads and writes history through jj or git.

- [vcs.VcsError](https://rosebud-biosciences.github.io/tether/reference/vcs.VcsError.html)
- [vcs.GitObjectReader](https://rosebud-biosciences.github.io/tether/reference/vcs.GitObjectReader.html)
- [vcs.JjAdapter](https://rosebud-biosciences.github.io/tether/reference/vcs.JjAdapter.html)
- [vcs.GitAdapter](https://rosebud-biosciences.github.io/tether/reference/vcs.GitAdapter.html)
- [vcs.CommitInfo](https://rosebud-biosciences.github.io/tether/reference/vcs.CommitInfo.html)
- [vcs.RefInfo](https://rosebud-biosciences.github.io/tether/reference/vcs.RefInfo.html)
- [vcs.VcsAdapter](https://rosebud-biosciences.github.io/tether/reference/vcs.VcsAdapter.html)
- [vcs.git_env](https://rosebud-biosciences.github.io/tether/reference/vcs.git_env.html)
- [vcs.require_git_version](https://rosebud-biosciences.github.io/tether/reference/vcs.require_git_version.html)
- [vcs.detect_vcs](https://rosebud-biosciences.github.io/tether/reference/vcs.detect_vcs.html)
- [vcs.MIN_JJ_VERSION](https://rosebud-biosciences.github.io/tether/reference/vcs.MIN_JJ_VERSION.html)
- [vcs.MIN_GIT_VERSION](https://rosebud-biosciences.github.io/tether/reference/vcs.MIN_GIT_VERSION.html)

#### Errors

- [TetherError](https://rosebud-biosciences.github.io/tether/reference/TetherError.html): Base class for all tether errors
- [ConfigError](https://rosebud-biosciences.github.io/tether/reference/ConfigError.html): The repository configuration or manifest layout is invalid
- [VcsError](https://rosebud-biosciences.github.io/tether/reference/VcsError.html): A version-control operation failed
- [BackendError](https://rosebud-biosciences.github.io/tether/reference/BackendError.html): A backend operation failed
- [CapabilityError](https://rosebud-biosciences.github.io/tether/reference/CapabilityError.html): An operation was requested that the backend does not support
- [ImmutableObjectModified](https://rosebud-biosciences.github.io/tether/reference/ImmutableObjectModified.html): An object registered as immutable changed on disk / in storage
- [UnpinnedStateError](https://rosebud-biosciences.github.io/tether/reference/UnpinnedStateError.html): A pinnable object has working state that was never pinned
- [PinDriftError](https://rosebud-biosciences.github.io/tether/reference/PinDriftError.html): A pin no longer resolves to the state recorded in the manifest
- [StaleWorkingCopyError](https://rosebud-biosciences.github.io/tether/reference/StaleWorkingCopyError.html): The workspace was forked from a manifest that no longer matches HEAD
- [StalePlanError](https://rosebud-biosciences.github.io/tether/reference/StalePlanError.html): A saved plan no longer matches the world it was computed from
- [MergeConflict](https://rosebud-biosciences.github.io/tether/reference/MergeConflict.html): A native merge stopped on conflicts; nothing was written
- [errors.RefMovedError](https://rosebud-biosciences.github.io/tether/reference/errors.RefMovedError.html)
- [MultiObjectError](https://rosebud-biosciences.github.io/tether/reference/MultiObjectError.html): Aggregates per-object failures from a fan-out operation