Basic Usage

The Workflow

# 1. Register a component
edgit components add prompt my-prompt components/prompts/analysis.md

# 2. Create a version
edgit tag create my-prompt v1.0.0

# 3. Push tags
edgit push --tags

# 4. Deploy to staging
edgit tag set my-prompt staging v1.0.0
edgit push --tags --force

# 5. Check status
edgit components list

That’s it. Everything else is details. Philosophy: Edgit’s job ends at git push. GitHub Actions handles deployment.

Register Components

Tell Edgit what files are components:

# Register a prompt
edgit components add prompt extraction-prompt components/prompts/extraction.md

# Register a config
edgit components add config api-config components/configs/api.json

# Register a query
edgit components add query analytics-query components/queries/analytics.sql

# Register a script
edgit components add script transform components/scripts/transform.ts

Or discover automatically:

# Scan for all components
edgit discover scan

# Detect a specific file
edgit discover detect src/my-function.ts
# Output: Type: script, Confidence: 95%

Create Versions

Use semantic versioning (v..):

# Create version tag
edgit tag create my-prompt v1.0.0

# List versions
edgit tag list my-prompt
# Output: v1.0.0, v1.1.0, v1.2.0

# View what changed
git show components/prompts/my-prompt/v1.0.0

Version multiple components:

edgit tag create extraction-prompt v1.0.0
edgit tag create analysis-config v2.1.0
edgit tag create validation-query v0.5.0

Each component gets its own independent version history. Tags use 4-level format:

components/prompts/my-prompt/v1.0.0 (version tag)
components/prompts/my-prompt/staging (environment tag)

The prefix (components/prompts/) is automatically inferred from the component type.

Deploy to Environment

Mark which versions are deployed to which environments:

# Deploy to staging
edgit tag set my-prompt staging v1.0.0
edgit push --tags --force

# Test in staging...
# All good? Deploy to production
edgit tag set my-prompt prod v1.0.0
edgit push --tags --force

# Deploy multiple components
edgit tag set extraction-prompt prod v1.0.0
edgit tag set analysis-config prod v2.1.0
edgit push --tags --force

Deployment is just metadata. Edgit creates tags like components/prompts/my-prompt/prod that point to v1.0.0. Your CI/CD reads these tags.

When to Use —force

Version tags: No --force needed. These are permanent markers.

edgit tag create my-prompt v1.0.0
edgit push --tags

Environment tags: --force required when moving environments.

edgit tag set my-prompt prod v1.0.0
edgit push --tags --force

Check Status

See what’s deployed where:

# Tree view
edgit components list --format tree
# Output:
# extraction-prompt (prompt)
#  v1.0.0 [prod]
#  v0.9.0 [staging]
#  v0.1.0

# Table view
edgit components list --format table
# Output:
# Component         Type    Latest   Prod     Staging
# extraction-prompt prompt  v1.0.0   v1.0.0   v0.9.0
# analysis-config   config  v2.1.0   v2.1.0   v2.0.0

# JSON (for scripts/CI)
edgit components list --format json

Rollback

Something broke? Rollback instantly:

# Rollback to previous version
edgit tag set my-prompt prod v0.9.0
edgit push --tags --force

# Or specific version
edgit tag set my-prompt prod v0.5.0
edgit push --tags --force

Rollback is instant (<50ms globally if you’ve deployed version data to Cloudflare KV).

View Versions

See component versions and details:

# List all versions
edgit tag list my-prompt
# Output: v1.0.0, v0.9.0, v0.8.0

# Show version details
edgit tag show my-prompt@v1.0.0
# Shows: commit, author, date, changes

Version Agents Too

Agents can be versioned just like components:

# Register an agent
edgit components add agent scraper agents/scraper/

# Version it
edgit tag create scraper v1.5.0

# Deploy it
edgit tag set scraper prod v1.5.0
edgit push --tags --force

# Now reference in ensembles

agents:
  - name: scraper
    agent: scraper@v1.5.0  # Locked to specific version

Common Patterns

Progressive Rollout

# Deploy to staging first
edgit tag set my-prompt staging v2.0.0
edgit push --tags --force

# Test thoroughly...

# Deploy to canary (10% of prod traffic)
edgit tag set my-prompt canary v2.0.0
edgit push --tags --force

# Monitor...

# Full prod rollout
edgit tag set my-prompt prod v2.0.0
edgit push --tags --force

A/B Testing

# Deploy variant A
edgit tag set my-prompt prod-variant-a v1.0.0
edgit push --tags --force

# Deploy variant B
edgit tag set my-prompt prod-variant-b v2.0.0
edgit push --tags --force

# Your ensemble references both

agents:
  - name: analyzer-a
    operation: think
    component: my-prompt@v1.0.0

  - name: analyzer-b
    operation: think
    component: my-prompt@v2.0.0

Emergency Rollback

# Production is broken!
# Check available versions
edgit tag list my-prompt

# Rollback to last known good
edgit tag set my-prompt prod v0.9.5
edgit push --tags --force

# Under 50ms later, you're back to working version

Use Edgit for All Git Operations

Remember: Edgit is 100% Git-compatible.

# Use edgit for everything
edgit add .
edgit commit  # AI-powered if OPENAI_API_KEY is set
edgit push
edgit pull
edgit checkout -b feature/new-prompt
edgit merge main

# All git commands work

Cheat Sheet

# Register
edgit components add <type> <name> <path>

# Version
edgit tag create <name> <version>
edgit tag list <name>
edgit tag show <name>@<version>

# Deploy
edgit tag set <name> <env> <version>
edgit push --tags --force

# Status
edgit components list
edgit components list --format tree|table|json

# Discover
edgit discover scan
edgit discover scan --type prompt|config|query|script
edgit discover detect <file>

# Standard git (all work with edgit)
edgit add|commit|push|pull|checkout|merge|...

Next Steps

Versioning Guide

Deep dive into versioning strategies

Deployment Strategies

Progressive rollouts, A/B testing, canaries

CI/CD Integration

Automate versioning in your pipeline

CLI Reference

Complete command documentation

Edgit

Getting Started

Guides

Reference

The Workflow

Register Components

Create Versions

Deploy to Environment

When to Use —force

Check Status

Rollback

View Versions

Version Agents Too

Common Patterns

Progressive Rollout

A/B Testing

Emergency Rollback

Use Edgit for All Git Operations

Cheat Sheet

Next Steps

Versioning Guide

Deployment Strategies

CI/CD Integration

CLI Reference

​The Workflow

​Register Components

​Create Versions

​Deploy to Environment

​When to Use —force

​Check Status

​Rollback

​View Versions

​Version Agents Too

​Common Patterns

​Progressive Rollout

​A/B Testing

​Emergency Rollback

​Use Edgit for All Git Operations

​Cheat Sheet

​Next Steps

Versioning Guide

Deployment Strategies

CI/CD Integration

CLI Reference

The Workflow

Register Components

Create Versions

Deploy to Environment

When to Use —force

Check Status

Rollback

View Versions

Version Agents Too

Common Patterns

Progressive Rollout

A/B Testing

Emergency Rollback

Use Edgit for All Git Operations

Cheat Sheet

Next Steps