hologit

hologit

A Git-native framework for declarative code automation that makes it simple to combine code from multiple sources and apply transformations efficiently.

Overview

Hologit enables you to define virtual "holobranches" within your Git repository that can:

1. Mix together content from:

   • The host branch
   • Other repositories/branches
   • Generated/transformed content

2. Apply transformations through "hololenses" using:

   • Docker containers
   • Chef Habitat packages

3. Project changes efficiently by:

   • Computing new git trees in memory
   • Caching results based on content
   • Watching for live updates Coming Soon

Key Concepts

Holobranches

A holobranch is a virtual branch defined in .holo/branches/ that specifies:

• What content to include from which sources
• How to transform that content through lenses
• Where the content should be placed in the output tree

Unlike regular Git branches, holobranches are computed on-demand and can mix content from multiple sources while maintaining clean history.

Holosources

Sources let you pull in code from:

• Other repositories via Git submodules
• Other branches in the same repository
• Remote Git repositories
• Output from local or remote holobranches

Sources are configured in .holo/sources/ and can be referenced by holobranches to include specific files or directories.

Hololenses

Lenses are transformations that can be applied to source content through:

• Docker containers that process input trees
• Habitat packages that provide build tools

Lenses are configured in .holo/lenses/ and can be chained together to form complex build pipelines.

Getting Started

1. Initialize hologit configuration:

git holo init

1. Create a holobranch:

git holo branch create my-branch

1. Add a source:

git holo source create https://github.com/example/repo

1. Project your holobranch:

git holo project my-branch

See the Installation Guide and Grand Tour for detailed setup and usage instructions.

Key Features

• Git-native: Works directly with Git's object database for maximum efficiency
• Content-based caching: Automatically caches build results based on input content, optionally sharing with other users and CI/CD via the same Git server hosting your project
• Declarative configuration: Define complex automation workflows in TOML files
• Live updates: Watch mode for continuous projection of changes Coming Soon
• GitHub Action: Materialize holobranches to real branches in CI/CD
• Flexible transformations: Use any build tool through containers or packages

Use Cases

• Monorepo Management: Combine code from multiple repositories while maintaining clean history
• Build Automation: Create efficient, reproducible build pipelines
• Documentation: Generate and publish documentation from multiple sources
• Deployment: Prepare deployment artifacts with consistent transformations
• Code Generation: Automate code generation and transformation workflows

Claude Code Plugin

Hologit includes an Agent Skill that gives your coding agent deep knowledge of hologit's configuration system, CLI, stock lenses, and workflows.

npx skills add --global JarvusInnovations/hologit

Once installed, your agent can help you configure .holo/ files, set up sources and mappings, choose and configure stock lenses, and debug projection issues.

Programmatic API

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

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 = "app"\n');

const workspace = new Workspace({
  root: rootTree,
  sources: {
    'base': { url: '/path/to/base', ref: 'refs/heads/main' },
    'overlay': { url: '/path/to/overlay', 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 });

See the Programmatic API docs for full details and the ProjectionPlan fluent builder API.

Rust Engine

The projection engine is being rewritten in Rust for performance, structured as two crates in a Cargo workspace:

• holo-tree — Shared git tree primitives: read, merge, and write git trees directly via gitoxide packfile access. Also usable by other projects like gitsheets.
• holo-projector — Holobranch projection engine: reads .holo/ config, resolves sources, composes trees. Depends on holo-tree.

The Rust engine produces hash-identical output to the Node.js implementation and runs ~130x faster on complex projections. It is integrated into the Node.js CLI and can also be used standalone:

cargo build --release -p holo-projector --features cli
./target/release/holo-project --repo . --ref HEAD my-branch

See each crate's README for details.

Documentation

• Installation Guide
• Repository Setup
• Holobranches Guide
• Holosources Guide
• Hololenses Guide
• Holoreactors Guide
• Working with Sources
• Programmatic API

License

This project is free and open source software.