Skip to main content
Product: Edgit Version: v1.0.0 Last Updated: 2025-11-01

​
Overview

This example demonstrates a complete Edgit workflow from initializing a repository to deploying a component to production.

​
Prerequisites

  • Edgit installed globally: npm install -g @ensemble/edgit
  • Git installed and configured
  • OpenAI API key (optional, for AI features)

​
Step 1: Initialize Repository

Create a new project and initialize Edgit: 
# Create project directory
mkdir my-functions && cd my-functions

# Initialize Git
git init
git config user.name "Your Name"
git config user.email "your@email.com"

# Initialize Edgit
edgit init
Output: 
✅ Edgit initialized in /path/to/my-functions
📝 Created .edgit/components.json
File structure: 
my-functions/
├── .git/
└── .edgit/
    └── components.json

​
Step 2: Create a Function

Create a simple email validation function: 
// src/validators/email.ts
export interface EmailValidationResult {
  valid: boolean;
  reason?: string;
}

export function validateEmail(email: string): EmailValidationResult {
  // Basic email validation
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

  if (!email) {
    return { valid: false, reason: 'Email is required' };
  }

  if (!emailRegex.test(email)) {
    return { valid: false, reason: 'Invalid email format' };
  }

  return { valid: true };
}

// Example usage
if (require.main === module) {
  console.log(validateEmail('test@example.com'));
  // { valid: true }

  console.log(validateEmail('invalid-email'));
  // { valid: false, reason: 'Invalid email format' }
}
File structure: 
my-functions/
├── .git/
├── .edgit/
│   └── components.json
└── src/
    └── validators/
        └── email.ts

​
Step 3: Register the Component

Add the function to Edgit’s component registry: 
edgit add function email-validator src/validators/email.ts \
  --description "Validates email addresses using regex"
Output: 
✅ Added component: email-validator (function)
   Path: src/validators/email.ts
   Description: Validates email addresses using regex
Updated registry (.edgit/components.json): 
{
  "version": "1.0",
  "components": {
    "functions": {
      "email-validator": {
        "type": "function",
        "path": "src/validators/email.ts",
        "description": "Validates email addresses using regex"
      }
    }
  }
}

​
Step 4: Commit Changes

Stage files and commit with AI-generated message: 
# Stage all changes
git add .

# Let AI generate commit message
edgit commit
AI analyzes the changes and generates: 
📝 AI generated message: "feat(email-validator): add email validation function"
✅ Committed: feat(email-validator): add email validation function
Or provide manual message: 
edgit commit -m "feat: add email validator with regex matching"

​
Step 5: Create Initial Version

Tag the first version: 
edgit tag email-validator v1.0.0
Output: 
✅ Created tag: email-validator-v1.0.0
   Component: email-validator
   Version: v1.0.0
   Commit: abc1234 feat(email-validator): add email validation function
Git tags: 
git tag
# email-validator-v1.0.0

​
Step 6: Push to Remote

Create a remote repository and push: 
# Add remote (replace with your repository URL)
git remote add origin git@github.com:username/my-functions.git

# Push code and tags
git push -u origin main
git push origin --tags
Output: 
To github.com:username/my-functions.git
 * [new branch]      main -> main
 * [new tag]         email-validator-v1.0.0 -> email-validator-v1.0.0

​
Step 7: Deploy to Staging

Mark version as deployed to staging: 
edgit deploy email-validator v1.0.0 --to staging
Output: 
✅ Deployed email-validator v1.0.0 to staging
   Timestamp: 2025-11-01 10:00:00

​
Step 8: Make Improvements

Add enhanced validation with domain checking: 
// src/validators/email.ts (updated)
export interface EmailValidationResult {
  valid: boolean;
  reason?: string;
}

// Common invalid domains to reject
const INVALID_DOMAINS = ['example.com', 'test.com', 'localhost'];

export function validateEmail(email: string): EmailValidationResult {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

  if (!email) {
    return { valid: false, reason: 'Email is required' };
  }

  if (!emailRegex.test(email)) {
    return { valid: false, reason: 'Invalid email format' };
  }

  // Check for invalid domains
  const domain = email.split('@')[1].toLowerCase();
  if (INVALID_DOMAINS.includes(domain)) {
    return { valid: false, reason: 'Invalid email domain' };
  }

  return { valid: true };
}
Commit the update: 
git add src/validators/email.ts
edgit commit
# AI: "feat(email-validator): add domain validation"

​
Step 9: Create Patch Version

Tag the improvement as a minor version: 
edgit tag email-validator v1.1.0
git push origin email-validator-v1.1.0

​
Step 10: Deploy to Production

After testing in staging, deploy to production: 
# Deploy v1.1.0 to production
edgit deploy email-validator v1.1.0 --to production \
  --metadata '{"deployer":"alice","ticket":"PROJ-123"}'
Output: 
✅ Deployed email-validator v1.1.0 to production
   Timestamp: 2025-11-01 14:30:00
   Metadata: {"deployer":"alice","ticket":"PROJ-123"}

​
Step 11: Check Status

View current deployment status: 
edgit status email-validator
Output: 
Component: email-validator (function)
Path: src/validators/email.ts
Description: Validates email addresses using regex
Latest version: v1.1.0

Versions:
  v1.1.0 (2025-11-01 12:00) - feat: add domain validation
  v1.0.0 (2025-11-01 10:00) - feat: add email validation function

Deployments:
  staging: v1.0.0 (deployed 2025-11-01 10:00:00)
  production: v1.1.0 (deployed 2025-11-01 14:30:00)

​
Step 12: View Component Details

List all components and view details: 
# List all components
edgit components list
Output: 
Type      Name              Path                        Description
function  email-validator   src/validators/email.ts     Validates email addresses...

# View detailed history
edgit components show email-validator --versions --deployments

​
Complete Command Summary

Here’s the complete sequence of commands: 
# 1. Setup
mkdir my-functions && cd my-functions
git init
edgit init

# 2. Create function
mkdir -p src/validators
cat > src/validators/email.ts << 'EOF'
export function validateEmail(email: string) {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}
EOF

# 3. Register and commit
edgit add function email-validator src/validators/email.ts \
  --description "Validates email addresses"
git add .
edgit commit  # AI generates message

# 4. Version and push
edgit tag email-validator v1.0.0
git remote add origin git@github.com:username/my-functions.git
git push -u origin main --tags

# 5. Deploy
edgit deploy email-validator v1.0.0 --to staging
edgit deploy email-validator v1.0.0 --to production

# 6. Check status
edgit status email-validator

​
Next Steps

Advanced Workflows

Managing multiple components in a monorepo

CI/CD Integration

Automate versioning and deployment

Component Dependencies

Track relationships between components

CLI Reference

Complete command documentation