> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Edgit
> Git-native versioning for AI components. Version every component independently, deploy any combination from history, rollback in under 50ms globally.
## What Edgit Does
Edgit extends Git with component-aware versioning. It tracks components (prompts, configs, queries, scripts, schemas), agents, and ensembles in a registry, uses Git tags for semantic versioning, and provides deployment tracking.
**Everything lives in Git.** No proprietary storage. No vendor database. You own the source of truth.
## Philosophy: A Thin Git Wrapper
Edgit's job ends at `git push`. It creates Git tags, updates the registry, and pushes to your repository. That's it.
**GitHub Actions handles everything after that.** Deployment, validation, notifications—all standard Git workflows. Edgit doesn't manage infrastructure, run webhooks, or orchestrate deploys. It's just Git with component awareness.
This keeps Edgit simple, portable, and compatible with any Git-based workflow you already have.
## The Problem It Solves
Modern AI systems have hundreds of independently evolving pieces:
* 50+ prompts
* 20+ agent implementations
* Dozens of SQL queries
* Multiple config files
* Various scripts and transforms
**Traditional approach:** Everything gets the same version number. Change one prompt, bump the entire app to v2.0.0. Want to rollback? Revert the entire codebase.
**Edgit approach:** Each component versions independently. Mix optimal versions from different points in time. Rollback one component without touching anything else.
```bash theme={null}
# Version components independently
edgit tag create prompts/extraction v1.0.0
edgit tag create agents/company v2.1.0
edgit tag create queries/validation v0.5.0
edgit tag create schemas/invoice v1.0.0
edgit tag create ensembles/data-pipeline v1.0.0
# Deploy optimal combination
edgit tag set prompts/extraction prod v0.1.0 # Ancient but perfect
edgit tag set agents/company prod v3.0.0 # Latest stable
edgit tag set schemas/invoice prod v1.0.0 # Structured outputs
# Push tags to trigger deployment
edgit push --tags
```
## Core Features
### Component Versioning
**Components** are hot-swappable artifacts that don't require rebuilds:
* **Prompts** (`.md`) - AI instructions
* **Configs** (`.json`, `.yaml`) - Settings
* **Queries** (`.sql`) - Database queries
* **Scripts** (`.js`, `.ts`) - Reusable functions
* **Schemas** (`.json`) - JSON Schema for structured AI outputs
Each gets its own version history via Git tags.
```bash theme={null}
# Create version
edgit tag create prompts/extraction v1.0.0
# List versions
edgit tag list prompts/extraction
# Output: v1.0.0, v1.1.0, v1.2.0
# View changes
git show components/prompts/extraction/v1.0.0
```
### Agent Versioning
**Agents** are worker implementations that require rebuilds to deploy:
```bash theme={null}
# Version agent implementations
edgit tag create agents/scraper v1.5.0
edgit tag create agents/analyzer v2.0.0
# Set environment tags
edgit tag set agents/scraper prod v1.5.0
edgit tag set agents/analyzer prod v2.0.0
# Push tags
edgit push --tags
```
Now you can reference versioned agents in ensembles:
```yaml theme={null}
ensemble: my-workflow
agents:
- name: scraper
agent: scraper@v1.5.0 # Locked to specific version
- name: analyzer
agent: analyzer@v2.0.0 # Different version
component: prompt@v1.0.0 # With specific prompt version
```
### Ensemble Versioning
**Ensembles** are workflow definitions that orchestrate agents. They can be written in YAML or TypeScript:
```bash theme={null}
# Version TypeScript ensembles
edgit tag create ensembles/data-pipeline v1.0.0
# Version YAML ensembles
edgit tag create ensembles/scraping-workflow v2.0.0
# Set environment tags
edgit tag set ensembles/data-pipeline prod v1.0.0
```
TypeScript ensembles provide full type safety:
```typescript theme={null}
// ensembles/data-pipeline.ts
import { createEnsemble, step, parallel } from '@ensemble-edge/conductor'
export default createEnsemble('data-pipeline')
.addStep(
parallel('analyze')
.steps(
step('sentiment').operation('think').config({ prompt: '...' }),
step('entities').operation('think').config({ prompt: '...' })
)
)
.build()
```
### Git Tag Namespace
All tags use a 4-level format: `{prefix}/{type}/{name}/{slot}`
```bash theme={null}
# Components (hot-swappable)
components/prompts/extraction/v1.0.0
components/prompts/extraction/prod
components/queries/validation/v0.5.0
components/queries/validation/staging
# Logic (requires rebuild)
logic/agents/scraper/v1.5.0
logic/agents/scraper/prod
logic/ensembles/data-pipeline/v1.0.0
logic/ensembles/data-pipeline/prod
```
**Prefix meanings:**
* `components/` - Hot-swappable artifacts (prompts, queries, configs, scripts, schemas)
* `logic/` - Requires rebuild to deploy (agents, ensembles)
**Type examples:**
* `prompts/`, `queries/`, `configs/`, `scripts/`, `schemas/` (under `components/`)
* `agents/`, `ensembles/` (under `logic/`)
**Slot types:**
* Semantic versions: `v1.0.0`, `v2.1.3`
* Environment tags: `prod`, `staging`, `dev`
The prefix is automatically inferred from the file location in your repository.
### Tag Commands
```bash theme={null}
# Create immutable version tag
edgit tag create prompts/extraction v1.0.0
# Set mutable environment tag
edgit tag set prompts/extraction prod v1.0.0
edgit tag set agents/scraper staging v2.0.0-beta
# Push tags to trigger deployment
edgit push --tags
edgit push --tags --force # Force update remote tags
```
### Deployment Tracking
Know exactly what's deployed where:
```bash theme={null}
# Check status
edgit components list --format tree
# Output:
# extraction (prompt)
# v1.0.0 [prod]
# v0.9.0 [staging]
# v0.1.0
# View versions
edgit tag list prompts/extraction
# Output: v1.0.0, v0.9.0, v0.1.0
# View version details
edgit tag show prompts/extraction@v1.0.0
```
### Component Discovery
Find and register components automatically:
```bash theme={null}
# Scan repository for components
edgit discover scan --type prompt
# Found 12 prompt files
# Scan for TypeScript ensembles
edgit discover scan --type ensemble
# Found 5 ensemble files
# Detect component type
edgit discover detect src/my-function.ts
# Type: script
# Confidence: 95%
# Suggested name: my-function
# List untracked components
edgit components list --untracked
# Shows files detected as components but not yet registered
```
## Use Edgit For Everything
**Edgit is 100% Git-compatible.** Every `git` command works as an `edgit` command.
```bash theme={null}
# Use edgit for all version control
edgit init
edgit add src/
edgit commit # AI-powered if OPENAI_API_KEY set
edgit push origin main
edgit checkout -b feature/new-prompt
edgit merge main
```
### Why Use Edgit Instead of Git?
Type `edgit` for all operations. No mental switching between tools.
Edgit understands your components in ALL operations - not just tagging.
We can enhance any Git command later (smarter merging, better diffs, etc.)
Edgit passes through to Git for standard operations. Identical behavior.
## The Versioning Multiverse
With independent versioning of components, agents, AND ensembles, you unlock infinite combinations:
```yaml theme={null}
# Test matrix:
# 2 agent versions × 3 prompt versions × 2 configs = 12 variants
ensemble: multiverse-test
agents:
# Variant 1: Stable everything
- name: stable
agent: analyzer@v1.0.0
component: prompt@v1.0.0
config: config@v1.0.0
# Variant 2: New agent, old prompt
- name: new-agent-old-prompt
agent: analyzer@v2.0.0
component: prompt@v1.0.0
config: config@v1.0.0
# ... 10 more combinations for A/B testing
```
```typescript theme={null}
// ensembles/multiverse-test.ts
import { createEnsemble, step, parallel } from '@ensemble-edge/conductor'
export default createEnsemble('multiverse-test')
.addStep(
parallel('variants')
.steps(
// Variant 1: Stable everything
step('stable')
.agent('analyzer@v1.0.0')
.component('prompt@v1.0.0')
.config({ configRef: 'config@v1.0.0' }),
// Variant 2: New agent, old prompt
step('new-agent-old-prompt')
.agent('analyzer@v2.0.0')
.component('prompt@v1.0.0')
.config({ configRef: 'config@v1.0.0' })
)
)
.build()
```
### Time Travel
Reproduce bugs from last week by recreating the exact environment:
```bash theme={null}
# View tag history using Git
git log --oneline refs/tags/components/prompts/extraction
# Recreate exact environment
edgit tag set prompts/extraction debug v3.1.0
edgit tag set agents/processor debug v1.9.2
```
## Next Steps
Detailed setup instructions
Learn the essential commands
Master component and agent versioning
Complete command documentation
Edgit is open source and free to use. Version data lives in your Git repository, not our servers.
You own everything.