Revision Management

Version control functionality for managing different revisions of deployed projects, enabling rollbacks, staged deployments, and revision history management.

Capabilities

Rollback

Revert a project to the previous revision.

/**
 * Revert project to previous revision
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function rollback(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Rollback interactive domain selection
surge rollback

# Rollback specific domain
surge rollback example.surge.sh

Reverts the live project to the previously deployed revision. Useful for quickly undoing problematic deployments.

Library Usage:

surge.rollback({})(process.argv.slice(2));

Roll Forward

Advance a project to the next revision (opposite of rollback).

/**
 * Advance project to next revision
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function rollfore(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Roll forward interactive domain selection
surge rollfore

# Roll forward specific domain
surge rollfore example.surge.sh

Moves the live project forward to the next available revision in history.

Library Usage:

surge.rollfore({})(process.argv.slice(2));

Cutover

Switch to the latest revision of a project.

/**
 * Switch project to latest revision
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function cutover(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Cutover interactive domain selection
surge cutover

# Cutover specific domain
surge cutover example.surge.sh

Switches the live project to the most recent revision, effectively "catching up" if the project is behind.

Library Usage:

surge.cutover({})(process.argv.slice(2));

Discard Revision

Remove a specific revision from the system permanently.

/**
 * Remove revision from system permanently
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function discard(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Discard with interactive selection
surge discard

# Discard from specific domain
surge discard example.surge.sh

Permanently removes a revision from the system. This action cannot be undone.

Library Usage:

surge.discard({})(process.argv.slice(2));

Select Revision

Select a specific revision to make it the active deployment.

/**
 * Select specific revision as active deployment
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function select(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Select with interactive menu
surge select

# Select from specific domain
surge select example.surge.sh

Presents an interactive menu of available revisions and allows selection of which one should be live.

Library Usage:

surge.select({})(process.argv.slice(2));

Revision System

How Revisions Work

• Each surge publish creates a new revision
• Revisions are immutable once created
• Live traffic always serves from the "active" revision
• Multiple revisions can exist simultaneously
• Revisions include full file snapshots

Revision Metadata

Each revision contains:

• Timestamp: When the revision was created
• File Count: Number of files in the revision
• Total Size: Combined size of all files
• Commit Message: Optional message for the revision
• User: Who created the revision

Revision Limits

• Number of stored revisions varies by plan
• Older revisions are automatically pruned
• Critical revisions can be marked for retention

Deployment Strategies

Blue-Green Deployments

Use revisions to implement blue-green deployment patterns:

1. Deploy new version (creates new revision)
2. Test new revision on staging domain
3. Use cutover to switch live traffic
4. Keep previous revision as rollback option

Staged Rollouts

Deploy with preview mode, then promote:

# Deploy to preview
surge --preview ./build preview.example.surge.sh

# After testing, deploy to production
surge ./build example.surge.sh

# If issues arise, rollback
surge rollback example.surge.sh

Canary Releases

Combine revision management with traffic splitting:

1. Deploy new revision
2. Route small percentage of traffic to new revision
3. Monitor metrics and errors
4. Gradually increase traffic or rollback if issues

Revision CLI Options

Message Annotation

Add descriptive messages to revisions:

surge --message "Fix navigation bug" ./build example.surge.sh

The message helps identify revisions in the revision history.

Staging Environments

Use preview mode for testing revisions:

# Deploy to staging first
surge --stage ./build staging.example.surge.sh

# After verification, deploy to production
surge ./build example.surge.sh

Integration with Version Control

Git Integration

Sync revisions with git commits:

# Use git commit message for revision
COMMIT_MSG=$(git log -1 --pretty=%B)
surge --message "$COMMIT_MSG" ./build example.surge.sh

Automated Deployment

Integrate revision management in CI/CD:

# GitHub Actions example
- name: Deploy to staging
  run: surge --stage ./build staging.example.surge.sh
  
- name: Run tests against staging
  run: npm run test:e2e
  
- name: Deploy to production
  run: surge ./build example.surge.sh
  if: success()
  
- name: Rollback on failure
  run: surge rollback example.surge.sh
  if: failure()

Monitoring Revisions

Revision History

Use surge list to view revision history:

surge list example.surge.sh

Shows table with:

• Revision timestamps
• File counts and sizes
• Active revision indicator
• Revision messages

Tracking Changes

Monitor revision changes:

• File additions/deletions
• Size changes
• Deployment frequency
• Rollback frequency

Error Handling

Revision Management Errors

• No Revisions Available: Project has no deployment history
• Revision Not Found: Specified revision doesn't exist
• Active Revision: Cannot discard currently active revision
• Permission Denied: User lacks revision management permissions

All revision commands provide clear error messages and suggested actions.