Installation

npm install -g babbage
# or
npx babbage

Quick Start

# Compare build artifacts between two branches
npx babbage run ./my-repo \
  --base main \
  --head feature-branch \
  --include "src/**/*.js" \
  -o diff.html

This command:

Switches to main branch → builds → captures artifacts
Switches to feature-branch → builds → captures artifacts
Generates an HTML diff of the two results

Include Pattern (Required)

The --include option is required and specifies files to capture using glob patterns.

Pattern Guidelines

# Good: Specific paths
--include "apps/web/src/**/*.mjs"      # Only specific app's src
--include "src/**/*.js"                 # Only JS under src
--include "dist/**/*.js"                # Only dist folder
# Bad: Too broad
--include "**/*.mjs"                    # May include node_modules
--include "*.js"                        # All JS files

Multiple Patterns

# Use multiple --include options
babbage run . --base main --head feature \
  --include "apps/web/src/**/*.mjs" \
  --include "packages/lib/src/**/*.js"

Configuration File

Create a .babbage file in your project root:

{
  "buildCommand": "pnpm build",
  "include": [
    "apps/web/src/**/*.mjs",
    "packages/lib/src/**/*.js"
  ]
}

CLI Commands

`run` - Full Pipeline

The most common usage. Runs the entire comparison process at once.

babbage run <repo> --base <branch> --head <branch> [options]

Examples:

# Basic usage
babbage run . --base main --head feature/new-ui --include "src/**/*.js"
# Custom build command
babbage run . --base main --head develop \
  --build "npm run build" \
  --include "dist/**/*.js"
# Multiple patterns
babbage run . --base main --head feature \
  --include "apps/web/src/**/*.mjs" \
  --include "packages/lib/src/**/*.js"
# Save output to file
babbage run . --base main --head feature \
  --include "src/**/*.js" \
  -o diff.html
# Skip git push (for local testing)
babbage run . --base main --head feature \
  --include "src/**/*.js" \
  --no-push

`capture` - Single Branch Capture

Capture build artifacts from a specific branch. Useful when one branch is already captured.

babbage capture <repo> <branch> [options]

Examples:

babbage capture . main --include "src/**/*.js"
babbage capture . feature-branch \
  --build "yarn build" \
  --include "dist/**/*.js"

`diff` - Generate Diff HTML

Generate diff HTML from already captured branches.

"babbage diff