Programmatic API

Hologit can be used as an npm module to compose git trees programmatically, without .holo/ TOML configuration files in the source repositories.

Installation

npm install hologit

Exported API

const {
  Git,          // Git CLI wrapper
  Repo,         // Git repository instance
  Workspace,    // Container for sources, branches, and lenses
  Branch,       // A holobranch with mappings
  Source,       // A holosource (remote git ref)
  Mapping,      // A holomapping (source → output path)
  Lens,         // A hololens (transformation)
  Projection,   // Orchestrates composition + lens pipeline
  TreeObject,   // In-memory git tree representation
  BlobObject,   // In-memory git blob representation
  SpecObject,   // Content-addressable spec for caching
  Studio,       // Docker execution environment manager
} = require('hologit');

Two Modes of Use

TOML-driven (traditional)

Hologit reads .holo/sources/*.toml, .holo/branches/*/*.toml, and .holo/lenses/*/*.toml from a git tree to define the composition. This is how the git holo project CLI works.

const { Repo, Projection } = require('hologit');

const repo = await Repo.getFromEnvironment();
const workspace = await repo.getWorkspace();
const branch = await workspace.getBranch('my-holobranch');
const treeHash = await Projection.projectBranch(branch);

Programmatic (no TOML required)

Sources, branches, and mappings are constructed in memory using the phantom config mechanism. The source repositories don’t need any .holo/ directory.

const { Repo, Workspace, Branch, Projection } = require('hologit');

const repo = new Repo({ gitDir: '/path/to/.git', ref: 'HEAD' });
const rootTree = repo.createTree();
await rootTree.writeChild('.holo/config.toml', '[holospace]\nname = "my-project"\n');

const workspace = new Workspace({
  root: rootTree,
  sources: {
    'base': { url: '/path/to/base-repo', ref: 'refs/heads/main' },
    'overlay': { url: '/path/to/overlay-repo', ref: 'refs/heads/main' }
  }
});

const branch = new Branch({
  workspace,
  name: 'composed',
  phantom: {},
  mappings: {
    '_base': { holosource: 'base', files: ['**'] },
    '_overlay': { holosource: 'overlay', files: ['**'], after: ['base'] }
  }
});

const treeHash = await Projection.projectBranch(branch, { lens: false });

The result is a git tree hash — the same content-addressable output that the CLI produces. You can check it out, diff it, or compose it further.

Guides

• Composition — How to compose git trees programmatically
• ProjectionPlan — Fluent builder API for common composition patterns