Repository integration
Advanced: assumes basic shell commands, Python environments, and Git. Use this guide when you want to manage a project’s definitions in a code repository. Ordinary graph use and saving a graph do not require Git or repository initialization.
GraphForge uses one .graphforge/ directory. Definitions in graphforge.yaml,
ontology/, schemas/, seeds/, and migrations/ are ordinary reviewable Git
content. Runtime state, imports, and exports are data and must not be committed.
Follow Installation to install GraphForge. The examples below use graphforge from that activated Python
environment. Open a terminal at the root of the Git repository you intend to
manage. Durable state needs supported storage.
graphforge --versiongraphforge --project-dir . initAlternatively, replace graphforge in the commands below with
npx @curatelabs/graphforge-cli@next (latest pre-release) or
npx @curatelabs/graphforge-cli (latest release). The npm package also supplies the gf
alias; the Python package supplies only graphforge. Run one launcher, not
both initialization paths.
Both launchers forward arguments to the Rust CLI and preserve its exact stdout, stderr, structured JSON, and exit status. They do not contain Python or JavaScript fallback implementations.
init installs the compatible project-local GraphForge skills into
.agents/skills/ unless --no-skills is supplied. The wheel and npm package
carry byte-identical offline assets generated from the repository’s single
project-skills/ source. GraphForge owns only the skill files recorded in its
versioned managed manifest: unrelated skills and user edits are preserved, and
skills status reports conflicts before skills update or skills remove
can change them.
graphforge --project-dir . skills installgraphforge --project-dir . skills status --jsonUse skills update when intentionally refreshing installed guidance, or
skills remove when intentionally removing it. These are separate maintenance
actions, not steps to run after every installation.
The installed skills are tracked repository guidance, not graph data. Do not
blanket-ignore .agents/skills/; review and commit the GraphForge skill
directories and their managed provenance manifest when the team wants the same
agent experience across clones.
graphforge --project-dir . config validategraphforge --project-dir . config resolve --jsongraphforge --project-dir . sync --check --jsongraphforge --project-dir . sync \ --idempotency-key 41414141-4141-4141-4141-414141414141 \ --actor-uuid 42424242-4242-4242-4242-424242424242 \ --jsonCommands discover the nearest Git worktree when --project-dir is omitted.
init preserves existing .gitignore content while managing the four runtime
exclusions selected by ADR 0016, including the persistent parent-scoped
admission lock for .graphforge/state/. It refuses to proceed if any managed
data path is already tracked. sync validates only declared definition paths
and digest-addressed sources; it never scans or ingests the repository
implicitly. remove requires --yes and deletes only
.graphforge/state/; the admission lock remains as the stable crash/retry
rendezvous. Tracked definitions, project-local skills, imports, exports,
external datasets, and credentials are left alone.
The stable machine interface is selected with global --json. Configuration
resolution always emits canonical compact JSON and never resolves secret values.
Repository lifecycle receipts identify files and directories relative to the
discovered repository root, using / separators. They never expose a checkout,
home-directory, or other machine-private absolute path.
Successful Arrow-backed commands use the versioned
graphforge-cli-result/1 JSON envelope when --json is selected. The envelope
is schema-first: columns declares each name, Arrow data type, and nullability
before metadata and positional rows. UUID and binary values use canonical
portable text encodings. The default output remains Arrow IPC.
JSON failures use a stable error object with ordered code, message, and
bounded safe details. Details may identify the operation or a
repository-relative path, but never include credentials, raw data, unrestricted
paths, descriptions, or revert reasons. Parse failures and runtime failures
retain their established nonzero exit codes.
Checkpoint inspection and revert
Section titled “Checkpoint inspection and revert”Checkpoint metadata inspection and checkpoint queries are separate:
graphforge --project-dir . checkpoint show before-changegraphforge --project-dir . checkpoint open before-change -- \ "MATCH (n) RETURN n"checkpoint show resolves and verifies the authoritative active checkpoint
record, then returns the same one-row metadata schema used by checkpoint list. checkpoint open remains the read-only query surface and never creates
a mutable shell. Global --json selects the schema-first JSON result for
checkpoint commands; without it, the native result is Arrow IPC.
Revert is fail-closed. Preview resolves the checkpoint and current generation without publishing anything and does not require mutation identity:
graphforge --project-dir . --json revert before-change --previewOnly after inspecting the preview and choosing to replace the current state
with the checkpoint, run the following revert. It requires --reason,
--idempotency-key, and explicit confirmation with --yes:
graphforge --project-dir . revert before-change \ --reason "restore known state" \ --idempotency-key 4f6a9b78-887d-4b8e-872b-a8b59059f777 \ --yesOmitting --yes refuses the mutation. Successful and idempotently replayed
receipts identify the prior current generation so automation can relate the
previewed state to the published result.
Remove repository runtime state
Section titled “Remove repository runtime state”Removal is an optional destructive maintenance action. It deletes
.graphforge/state/, including the local graph, rather than closing the project.
Export any state you need to keep first. Inspect graphforge remove --help and
use graphforge --project-dir . remove --yes only when you intend that deletion.
This is not part of setup or synchronization.
Repository synchronization
Section titled “Repository synchronization”sync --check compares the current repository inputs with the authoritative
workspace/repository_snapshot@1 participant without changing CURRENT or
creating a generation. It prints in_sync and exits successfully when the
snapshots match; drift prints drift and exits with status 4. With --json,
both outcomes use the same deterministic receipt. The persisted participant is
closed by
repository-snapshot-v1.schema.json.
A mutating sync publishes only when drift exists and then requires a
caller-owned --idempotency-key; --actor-uuid is optional but cannot be
supplied without the operation identity. The snapshot contains only the
secret-free resolved-config digest, ordered validated-definition digests,
ordered external source IDs and declared checksums, bounded Git commit/dirty
provenance, and caller identity. It contains no definition contents, source or
graph data, secrets, diffs, commit messages, or unrestricted paths.
Publication replaces only the repository snapshot participant in one complete generation. Ontology, configuration, graph, knowledge, and every other participant remain byte-identical. Reusing the same operation and actor for the same desired state is an idempotent replay; reusing that operation for different state or a different actor fails closed. A different operation on unchanged desired state is a no-op and is not recorded.
Portable export and import
Section titled “Portable export and import”Portable interchange moves one complete, immutable project generation without copying GraphForge’s live project layout. Select the current committed generation explicitly, or select the generation pinned by a named checkpoint:
graphforge --project-dir . export --current --output .graphforge/exports/current.gfpbgraphforge --project-dir . export --checkpoint before-change \ --output .graphforge/exports/before-change.gfpb--current is resolved when export starts. --checkpoint NAME resolves that
checkpoint’s pinned generation, even when a checkpoint is literally named
current. The two selectors are mutually exclusive. Export verifies the
selected manifest and every participant, then writes a versioned envelope with
the capability inventory, participant metadata, sizes, and integrity hashes in
canonical order. Identical selected state produces identical portable content.
An existing output path is rejected, preventing accidental replacement of a
previous export.
An envelope contains only the selected generation. It never contains CURRENT,
checkpoint registries, writer or lease locks, transaction journals, caches,
temporary files, trash, or another generation discovered beside the selected
one. It is therefore not a raw archive of .graphforge/state/.
Import accepts a streaming portable package only into a new, empty, or pristine
initialized project container. The pristine case is what makes import usable
immediately after graphforge init; any graph mutation or extra project artifact makes
the target ineligible:
graphforge --project-dir . import \ --input .graphforge/imports/incoming.gfpb \ --idempotency-key 4f6a9b78-887d-4b8e-872b-a8b59059f777Before any project mutation, import validates the envelope format and version,
bounded sizes and counts, canonical participant identities, source filesystem
type, every integrity hash, and every required capability version. Any failure
leaves the target without a newly published CURRENT (abort before linearize).
A successful import stages and verifies all participants into a durable
generation, then linearizes by atomically replacing or creating CURRENT, and
acknowledges only after the project-root platform-native namespace durability
barrier so reopen recovers the published generation. POSIX uses directory
fsync(2); fixed writable local NTFS uses the write-through same-handle rename
contract in ADR 0020,
while ReFS is unproven: it warns after successful primitive checks by default;
GRAPHFORGE_FILESYSTEM_DURABILITY=strict refuses it. Import does not merge into or overwrite an
existing project. These stage / validate / durable generation / linearize /
acknowledge / publish / abort / recover terms are the shared publication
vocabulary frozen by
ADR 0018; M5 interchange
issues (#738, #742, #745) consume that vocabulary rather than redefining it.
.graphforge/imports/ and .graphforge/exports/ are convenience transfer
areas, not durable project authority. Both are managed Git ignores, so envelopes
placed there remain outside the code repository. Keep tracked schemas,
ontology, migrations, and seed recipes separate from these data files.
This whole-project interchange surface is distinct from runtime-catalog
inspection, ontology suggestion and non-mutating validation, and explicit
YAML/JSON ontology-document export. #236 delivered those Rust-owned operations;
#237 delivered thin Python and Node parity plus durable ontology adoption and
clear. Repository export never substitutes for ontology export, and ontology
export never packages graph data or a project generation. Repository
initialization and synchronization preserve that authority boundary: they never
inspect a runtime catalog or suggest, validate, adopt, clear, or export an
ontology implicitly.
Continue a published Branch
Section titled “Continue a published Branch”Against a conforming publish-capable Hub, clone a named Branch, edit it through
the native research Branch API, then publish that same ref back. The clone keeps
the original Project and Branch UUID, creation record and selected head; the next
commit records that head as its first parent. Authors and committers remain exact
native record metadata and are always published: they appear in the lineage and,
as the derived people list with their roles, in the Project summary. Published
credit is public and permanent. Reopen and inspect historical records with
research_version; a metadata-only ancestor is not a retained payload.
The other advertised refs remain read-only remote citations. Immutable-Version
clones stay detached. Publishing divergent work is refused as non_fast_forward;
a stale repository revision is still ref_conflict. Neither refusal moves a ref.
Merge and explicit rewrite/prune are separate operations. Production hosted write
availability is independent of this native protocol behavior.
Explicit history replacement and retention
Section titled “Explicit history replacement and retention”Normal gf publish refuses divergent history. After reviewing the replacement,
gf publish <repository> --ref main --rewrite explicitly requests head replacement;
add --prune only to remove unreachable published Versions. The Hub must offer
history-mutation@1, authorize the repository operation and accept the current
revision lease. A concurrent update remains a conflict, never permission to
replace a newer head. Surviving refs and their history/dependencies remain live.
The reference Hub collects unreferenced objects after its documented 900-second
grace; local retained copies and independent Fork copies are unaffected.
For an established independent Fork, --check-fork-origin <repository URL> is an
optional origin diagnostic. A validated origin lineage missing the cited Version
warns and proceeds with the local copy. The citation contains no origin host, so
ordinary updates do not discover erasure automatically or probe another Hub.
See the publish contract for the precise
lease, identity, dependency and refusal rules.