cascade-cli 0.1.21

Stacked diffs CLI for Bitbucket Server
Documentation

Cascade CLI Banner

Rust CI Beta Release Tests

Cascade CLI improves Git workflows by enabling stacked diffs for Bitbucket Server - a powerful technique for managing chains of related commits as separate, reviewable pull requests. Perfect for feature development, bug fixes, and complex changes that benefit from incremental review.

📋 Table of Contents

✨ Key Features

🔄 Stacked Diff Workflow

  • Chain related commits into logical, reviewable stacks
  • Independent PR reviews while maintaining dependencies
  • Automatic rebase management when dependencies change
  • Smart force-push strategy to preserve review history
  • Smart conflict resolution - Auto-resolves 60-80% of common rebase conflicts

🏢 Team Integration

  • Bitbucket Server native integration
  • Pull request automation with dependency tracking
  • Team workflow enforcement via Git hooks
  • Progress tracking with real-time status updates

🖥️ Clean Interface

  • Interactive TUI for visual stack management
  • Shell completions (bash, zsh, fish)
  • Rich visualizations (ASCII, Mermaid, Graphviz, PlantUML)
  • Beautiful CLI with progress bars and colored output

🌿 How Stacked Diffs Work: Branch Management

Key Insight: Each Commit = Its Own Branch + PR

Cascade CLI automatically creates individual branches for each commit in your stack:

# You work normally (on main or a feature branch)
git checkout main  # or: git checkout -b my-feature-branch
ca stacks create feature-auth --base main

# Make commits as usual
git commit -m "Add user authentication endpoints"
git commit -m "Add password validation logic"  
git commit -m "Add comprehensive auth tests"

# Push to stack - Cascade CLI creates separate branches automatically:
ca push  # → Creates: add-user-authentication-endpoints
ca push  # → Creates: add-password-validation-logic  
ca push  # → Creates: add-comprehensive-auth-tests

# Submit creates individual PRs to main:
ca submit  # PR #101: add-user-authentication-endpoints → main
ca submit  # PR #102: add-password-validation-logic → main (depends on #101)
ca submit  # PR #103: add-comprehensive-auth-tests → main (depends on #102)

Two Workflow Options:

Option 1: Work on Main (Recommended for Solo Development)

git checkout main
ca stacks create feature-name --base main
# Make commits directly on main (they stay local until you push to remote)
# Cascade CLI handles all branch creation and PR management

Option 2: Work on Feature Branch (Team-Friendly)

git checkout -b feature-work
ca stacks create feature-name --base main
# Make commits on your feature branch
# Cascade CLI creates individual branches from your feature branch
# All PRs target main, not your feature branch

What You See vs. What Reviewers See:

You (Developer) Reviewers (Bitbucket)
Work on 1 branch See 3 separate PRs
3 commits in sequence Each PR focuses on 1 logical change
git log shows: A→B→C PR #101: A, PR #102: B, PR #103: C

The Magic: Auto-Generated Branch Names

Cascade CLI creates meaningful branch names from your commit messages:

"Add user authentication endpoints"   → add-user-authentication-endpoints
"Fix login timeout bug"              → fix-login-timeout-bug  
"Refactor password validation!!!"    → refactor-password-validation

🌟 Why Stacked Diffs?

Traditional Git workflows often result in:

  • Large, hard-to-review PRs
  • Blocked development waiting for reviews
  • Merge conflicts from long-lived branches
  • Lost context in massive changesets

Stacked diffs solve this by:

  • ✅ Small, focused PRs that are easy to review
  • ✅ Parallel development with dependency management
  • ✅ Reduced conflicts through frequent integration
  • ✅ Better code quality via incremental feedback

🚀 Quick Start

1. Installation

Quick Install (Recommended)

Universal Script (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/JAManfredi/cascade-cli/master/install.sh | bash

Package Managers:

# macOS - Homebrew (download formula first)
curl -O https://raw.githubusercontent.com/JAManfredi/cascade-cli/master/homebrew/cascade-cli.rb
brew install cascade-cli.rb
rm cascade-cli.rb

# Rust users
cargo install cascade-cli

Manual Installation

Pre-built Binaries:

# macOS (auto-detect architecture)
curl -L https://github.com/JAManfredi/cascade-cli/releases/latest/download/ca-macos-$(uname -m | sed 's/x86_64/x64/;s/arm64/arm64/').tar.gz | tar -xz
sudo mv ca /usr/local/bin/

# Linux (auto-detect architecture)  
curl -L https://github.com/JAManfredi/cascade-cli/releases/latest/download/ca-linux-$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/').tar.gz | tar -xz
sudo mv ca /usr/local/bin/

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/JAManfredi/cascade-cli/releases/latest/download/ca-windows-x64.exe.zip" -OutFile "ca.zip"
Expand-Archive -Path "ca.zip" -DestinationPath "$env:USERPROFILE\bin\"

From Source:

git clone https://github.com/JAManfredi/cascade-cli.git
cd cascade-cli
cargo build --release
cargo install --path .

See Installation Guide for detailed platform-specific instructions.

2. Initialize Your Repository

# Navigate to your Git repository
cd my-project

# Quick setup wizard (recommended)
ca setup

# Or manual initialization
ca init --bitbucket-url https://bitbucket.company.com

3. Create Your First Stack

# Create a new stack
ca stacks create feature-auth --base develop --description "User authentication system"

# Make multiple incremental commits (for your own tracking)
git add . && git commit -m "WIP: start authentication"
git add . && git commit -m "WIP: add login logic"
git add . && git commit -m "WIP: fix validation bugs"
git add . && git commit -m "Final: complete auth with tests"

# SQUASH + PUSH - Combine incremental commits into clean commit!
ca push --squash 4  # Squashes last 4 commits into 1

# OR: Make some commits normally, then squash later ones
git commit -m "Add core authentication logic"
ca push  # Push first clean commit

git commit -m "WIP: start tests"
git commit -m "WIP: more tests"  
git commit -m "Final: comprehensive test suite"

# SQUASH UNPUSHED - Only squash the last 3 commits
ca push --squash 3  # Squashes and pushes as second stack entry

# BATCH SUBMIT - Submit all unsubmitted entries as separate PRs!
ca submit

# Alternative options (for granular control):
ca push                               # Push all unpushed commits separately
ca push --since HEAD~3                # Push commits since reference
ca push --commits hash1,hash2,hash3   # Push specific commits
ca push --squash 4                    # Squash last 4 commits into 1 clean commit
ca push --squash-since HEAD~5         # Squash all commits since reference
ca submit                             # Submit all unsubmitted entries
ca submit --range 1-3                 # Submit entries 1 through 3
ca submit --range 2,4,6               # Submit specific entries

🔧 Git Hooks (Recommended)

Cascade CLI provides Git hooks that automate common stacked diff workflows:

Hook Name Purpose When It Runs
post-commit Auto-add commits to active stack with unique branch names After every git commit
pre-push Prevent force pushes, validate stack state Before git push
commit-msg Validate commit message format During git commit
prepare-commit-msg Add stack context to commit messages Before commit message editor 
# Install all hooks for automated workflow
ca hooks install

# Remove all hooks 
ca hooks uninstall

# Check installation status
ca hooks status

# Remove specific hooks
ca hooks remove post-commit                 # Remove auto-add behavior
ca hooks remove pre-push                    # Remove push protection
ca hooks remove commit-msg                  # Remove message validation
ca hooks remove prepare-commit-msg          # Remove message enhancement

🪝 Default hooks installed:

  • Pre-push: Prevents force pushes that break stack integrity
  • Commit-msg: Validates commit message quality
  • Prepare-commit-msg: Adds helpful stack context

📚 Complete Hooks Guide - Detailed explanation of each hook, troubleshooting, and advanced usage

💡 Pro tip: The post-commit hook (auto-add commits to stack) is available but not installed by default to avoid conflicts with existing repo hooks.

# Install optional post-commit hook if no conflicts
ca hooks install post-commit

💡 Installation Tips:

  • For full automation: Install all hooks with ca hooks install
  • For manual control: Remove post-commit hook, keep others for safety
  • For team safety: Always keep pre-push to prevent stack corruption

4. Experience the Magic

# Check your stack status
ca stack
# Stack: feature-auth (3 entries)
# Entry 1: [abc123] Add authentication endpoints → PR #101
# Entry 2: [def456] Add password validation → PR #102  
# Entry 3: [ghi789] Add comprehensive tests → PR #103

# Monitor and auto-merge approved PRs
ca autoland
# ✅ Monitoring PRs for approval + passing builds
# ✅ Will auto-merge in dependency order when ready

🛡️ Safe Development Flow (Recommended)

Cascade CLI protects against accidentally polluting your base branch:

# ✅ SAFE: Start on base branch, but work on feature branches
git checkout main
ca stacks create my-feature --base main

# Make your changes
git checkout -b feature/auth-system  # Create feature branch
git commit -am "Add user authentication"
git commit -am "Add password validation"

# Push to stack (automatically tracks source branch)
ca push  # Adds all unpushed commits to stack with source tracking

🚀 Auto-Branch Creation (Even Safer)

Let Cascade CLI handle branch creation automatically:

# If you accidentally work on main...
git checkout main
# (make commits directly on main - oops!)

# Cascade CLI will protect you:
ca push --auto-branch  # Creates feature branch & moves commits safely

🎯 Smart Interactive Edit Mode

When editing stack entries, Cascade CLI intercepts your Git commands and provides smart interactive guidance:

ca entry checkout 1  # Enter edit mode for first entry

# Just commit normally - the system takes care of the rest!
git commit

# ⚠️ You're in EDIT MODE for a stack entry!
#
# Choose your action:
#   🔄 [A]mend: Modify the current entry
#   ➕ [N]ew:   Create new entry on top (current behavior) 
#   ❌ [C]ancel: Stop and think about it
#
# Your choice (A/n/c): A
#
# ✅ Running: git commit --amend
# [Opens editor for amending]
# 💡 Entry updated! Run 'ca sync' to update PRs

No more remembering commands - just type git commit and Cascade guides you to the right action automatically!

🔍 Scattered Commit Detection & Auto-Fix

Cascade CLI detects when you're adding commits from different Git branches to the same stack and provides automatic resolution options:

# This creates a "scattered commit" problem:
git checkout feature-branch-1
git commit -m "Add user auth"
git checkout feature-branch-2  
git commit -m "Add admin panel"
git checkout main

# When you push both to the same stack:
ca push

# ⚠️  WARNING: Scattered Commit Detection
#    You've pushed commits from different branches:
#    - feature-branch-1 (1 commit)
#    - feature-branch-2 (1 commit)
#    
#    This makes branch cleanup confusing after merge.
#    Consider organizing commits into separate stacks instead.

# 🔧 Modern Fix: Use validation to detect and resolve
ca validate --fix incorporate  # Automatically incorporate extra commits
ca validate --fix split        # Split extra commits into new stack entries

📝 Smart PR Creation

Cascade CLI automatically generates meaningful pull request titles and descriptions:

# Create draft PRs for review:
ca submit --draft

# Each PR gets intelligent metadata:
# ┌─ PR Title: Generated from commit messages
# ├─ Description: Combines commit details & context  
# ├─ Branch: Auto-created with semantic naming
# └─ Target: Points to previous stack entry or base

# Custom titles and descriptions:
ca submit 2 --title "Add advanced user auth" --description "Implements JWT tokens with refresh capabilities"

# Default behavior (auto-generated):
ca submit  # Creates well-structured PRs

How PR Content is Generated:

  • Title: Uses your commit message or most significant change
  • Description: Includes commit details, file changes, and stack context
  • Branch Context: Shows relationship to previous entries
  • Target Branch: Automatically set to build on previous stack entry

Daily Development Flow

Cascade CLI follows a simple, powerful workflow optimized for modern development:

# 1. Create & Develop
ca stacks create feature-name --base main
git commit -m "Add core functionality"
git commit -m "Add comprehensive tests"

# 2. Push & Submit (with modern shortcuts)
ca push --squash 2    # Combine commits into reviewable unit
ca submit            # Create PR with automatic dependency tracking

# 3. Auto-Land (set and forget)
ca autoland          # Monitors and merges when approved + tests pass

# 4. Iterate (if review feedback)
git commit --amend   # Update based on feedback
ca sync              # Update all dependent PRs automatically

🔄 Advanced Workflows: See our comprehensive Workflows Guide for complex scenarios including:

  • Multi-commit stacks with dependencies
  • Handling review feedback on middle commits
  • Managing emergency hotfixes during feature development
  • Cross-team collaboration patterns
  • Base branch updates with smart force push
  • Modern WIP-to-clean commit workflows

🤖 Smart Conflict Resolution

Automatic Conflict Resolution

Cascade CLI automatically resolves 60-80% of common rebase conflicts using intelligent pattern recognition.

✅ Resolved Automatically

  • Import statement conflicts - Merges and deduplicates imports
  • Dependency version conflicts - Uses latest compatible versions
  • Simple formatting conflicts - Applies consistent code style
  • Non-overlapping changes - Safely combines independent modifications

How It Works

  • Pattern Recognition: Analyzes conflict types using AST parsing
  • Safe Resolution: Only resolves conflicts with zero ambiguity
  • Manual Fallback: Escalates complex conflicts to developer review
  • Audit Trail: Logs all automatic resolutions for transparency
# Smart conflict resolution in action
ca rebase
# 🤖 Auto-resolved 3 import conflicts in src/auth.rs
# 🤖 Auto-resolved 1 dependency conflict in package.json
# ⚠️  Manual resolution needed: 1 logic conflict in src/validation.rs

Supported File Types for Import Resolution

  • JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
  • Python (.py)
  • Rust (.rs)
  • Swift (.swift)
  • Kotlin (.kt)
  • C# (.cs)

Benefits

  • Faster rebases - No manual intervention for simple conflicts
  • Consistent results - Deterministic conflict resolution
  • Reduced errors - Eliminates common merge mistakes
  • Learning system - Improves resolution patterns over time

Configuration

# Enable/disable smart resolution
ca config set conflicts.auto_resolve true
ca config set conflicts.file_types "js,ts,py,rs"
ca config set conflicts.backup_on_resolve true

⚡ Essential Commands

# Stack Management (Multiple Stacks)
ca stacks create <name> --base <branch>  # Create new stack
ca stacks list                          # List all stacks
ca switch <name>                        # Switch active stack
ca push                                 # Add commits to current stack
ca submit                               # Submit PRs for current stack

# Current Stack Operations (Shortcuts)
ca stack                                # Show current stack details
ca push                                 # Push commits to stack
ca land                                 # Merge approved PRs
ca autoland                             # Auto-merge all ready PRs
ca sync                                 # Sync with remote repository
ca rebase                               # Rebase stack on updated base

# Branch Management & Safety
ca deactivate                           # Turn off stack mode
ca switch <name>                        # Switch to different stack

# Or use full commands when needed:
ca deactivate                           # Turn off stack mode (use normal Git workflow)  
ca switch <name>                        # Switch to different stack

# 🔍 Automatic branch change detection: Cascade detects when you switch branches
#     and prompts you to continue with current stack, deactivate, or switch stacks

# Entry Editing (Modern Convenience)
ca entry checkout [number]              # Interactive checkout for editing entries
ca entry status                         # Show current edit mode status  
ca entry list                           # List all entries with edit indicators

# Repository Overview
ca repo                                 # Show all stacks and repository status

💡 Pro tip: Use ca stack for current stack details, ca repo for everything overview.

📖 Command Reference

Stack Management

# Create and manage stacks
ca stacks create <name>                       # Create new stack (uses default base branch)
ca stacks create <name> --base <branch>       # Create stack with specific base branch
ca stacks create <name> -b <branch>           # Short form
ca stacks create <name> --description <desc>  # Add description
ca stacks create <name> -d <desc>             # Short form

# List stacks
ca stacks list                                # Show basic stack list
ca stacks list --verbose                      # Show detailed information
ca stacks list -v                             # Short form
ca stacks list --active                       # Show only active stack
ca stacks list --format <format>              # Custom output format

# Switch and view stacks
ca switch <name>                              # Activate stack
ca stack                                      # Show current stack details
ca stacks delete <name>                       # Remove stack
ca stacks delete <name> --force               # Force deletion without confirmation
ca validate                                   # Validate active stack
ca validate <name>                            # Validate specific stack

Entry Editing (Modern Convenience)

# Checkout specific entries for editing
ca entry checkout                           # Interactive picker to select entry
ca entry checkout 1                         # Checkout first entry for editing
ca entry checkout 3 --yes                   # Skip confirmation prompts
ca entry checkout 2 --direct                # Skip picker when using entry number

# Track edit status
ca entry status                             # Show current edit mode info
ca entry status --quiet                     # Brief status only
ca entry list                               # List all entries with edit status
ca entry list --verbose                     # Show detailed entry information

Adding Commits to Stack

# Basic push operations
ca push                                      # Add current commit (HEAD) to stack
ca push --branch <name>                      # Custom branch name for this commit
ca push -b <name>                            # Short form
ca push --message <msg>                      # Custom commit message
ca push -m <msg>                             # Short form  
ca push --commit <hash>                      # Push specific commit instead of HEAD

# Batch operations
ca push                                      # Push all unpushed commits separately
ca push --since HEAD~3                       # Push commits since reference
ca push --commits hash1,hash2,hash3          # Push specific commits

# Smart squash operations
ca push --squash 4                           # Squash last 4 commits into 1 clean commit
ca push --squash-since HEAD~5                # Squash all commits since reference

# Remove from stack
ca pop                                       # Remove top entry from stack
ca pop --keep-branch                         # Keep the branch when popping

Pull Request Workflow

# Submit for review
ca submit                                    # Submit top entry (creates PR)
ca submit 2                                  # Submit specific entry number
ca submit --title <title>                    # Custom PR title
ca submit -t <title>                         # Short form
ca submit --description <desc>               # Custom PR description
ca submit -d <desc>                          # Short form

# Batch submission
ca submit                                    # Submit all unsubmitted entries
ca submit --range 1-3                        # Submit entries 1 through 3
ca submit --range 2,4,6                      # Submit specific entries

# Status and management
ca stacks status                             # Show active stack PR status
ca stacks status <name>                      # Show specific stack PR status
ca stacks prs                                # List all repository PRs
ca stacks prs --state open                   # Filter by state (open/merged/declined)
ca stacks prs --verbose                      # Show detailed PR information
ca stacks prs -v                             # Short form

Sync and Rebase Operations

# Sync with remote
ca sync                                      # Sync active stack with remote
ca sync --force                              # Force sync even with conflicts

# Rebase operations
ca rebase                                    # Rebase stack on latest base branch
ca rebase --interactive                      # Interactive rebase mode
ca rebase -i                                 # Short form
ca rebase --onto <branch>                    # Rebase onto different target branch
ca rebase --strategy cherry-pick             # Use specific rebase strategy
ca rebase --strategy three-way-merge         # Alternative strategies available
ca rebase --no-auto-resolve                  # Disable smart conflict resolution

# Rebase conflict resolution
ca stacks continue-rebase                    # Continue after resolving conflicts
ca stacks abort-rebase                       # Abort rebase operation
ca stacks rebase-status                      # Show rebase status and guidance

Advanced Tools

# Interactive interfaces
ca tui                                      # Launch terminal user interface

# Visualization and diagramming
ca viz stack                                # ASCII stack diagram for active stack
ca viz stack <name>                         # ASCII diagram for specific stack
ca viz deps                                 # Show dependency relationships
ca viz deps --format mermaid                # Export as Mermaid diagram
ca viz deps --format dot                    # Export as Graphviz DOT
ca viz deps --format plantuml               # Export as PlantUML
ca viz deps --output <file>                 # Save to file

# Git hooks integration
ca hooks install                            # Install all Git hooks
ca hooks uninstall                          # Remove all Git hooks
ca hooks status                             # Show hook installation status

# Individual hook management
ca hooks add post-commit                    # Install specific hook
ca hooks add pre-push                       # Install push protection  
ca hooks add commit-msg                     # Install commit message validation
ca hooks add prepare-commit-msg             # Install commit message enhancement
ca hooks remove post-commit                 # Remove specific hook
ca hooks remove pre-push                    # Remove push protection
ca hooks remove commit-msg                  # Remove message validation
ca hooks remove prepare-commit-msg          # Remove message enhancement

# Configuration and setup
ca setup                                    # Interactive setup: config + hooks + completions
ca completions install                      # Install shell completions
ca completions status                       # Check completion status
ca completions generate bash                # Generate completions for bash
ca completions generate zsh                 # Generate completions for zsh
ca completions generate fish                # Generate completions for fish

# System information
ca version                                  # Show version information
ca doctor                                   # Run system diagnostics

🔧 Configuration

Bitbucket Setup

# Interactive wizard (recommended)
ca setup

# Manual configuration
ca config set bitbucket.url "https://bitbucket.company.com"
ca config set bitbucket.project "PROJECT"
ca config set bitbucket.repository "repo-name"
ca config set bitbucket.token "your-personal-access-token"
ca config set bitbucket.username "your-username"
ca config set auth.method "token"  # or "basic"
ca config set default_reviewers "reviewer1,reviewer2"
ca config set stack.default_base "main"

🎨 Advanced Features

Terminal User Interface

Launch ca tui for an interactive stack browser with:

  • Real-time stack visualization
  • Keyboard navigation (↑/↓/Enter/q)
  • Live status updates
  • Error handling and recovery

Visualization Export

# Generate diagrams for documentation
ca viz stack --format mermaid --output docs/stack.md
ca viz deps --format dot --output diagrams/deps.dot

# Include in CI/CD pipeline
ca viz deps --format plantuml | plantuml -pipe > architecture.png

Shell Integration

# Install completions
ca completions install

# Check installation
ca completions status

# Manual installation
ca completions generate bash > /etc/bash_completion.d/ca

📝 Documentation

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Development Setup

git clone https://github.com/JAManfredi/cascade-cli.git
cd cascade-cli
cargo build
cargo test

Release Process

See Release Guide for maintainer instructions.

🔧 Development

Quick Development Setup

# Clone and build
git clone https://github.com/jared/cascade-cli.git
cd cascade-cli
cargo build

Pre-Push Validation

Always validate before pushing to GitHub! Run our comprehensive check script:

./scripts/pre-push-check.sh

This runs all the same checks as CI:

  • ✅ Code formatting and linting
  • ✅ Unit and integration tests
  • ✅ Documentation generation
  • ✅ Binary compilation

💡 Pro Tip: Set up a git hook to run this automatically:

# Add to .git/hooks/pre-push
#!/bin/sh
./scripts/pre-push-check.sh

CI Debugging Tools

Having trouble with CI failures that don't reproduce locally? We have specialized tools for that:

📋 Development Scripts Guide - Complete reference for all CI debugging and development scripts

See docs/DEVELOPMENT.md for complete development guidelines, testing strategies, and contribution workflows.

🏗️ Architecture

Cascade CLI is built with:

  • 🦀 Rust - Performance, safety, and reliability
  • 📚 git2 - Native Git operations without subprocess overhead
  • 🌐 HTTP/REST - Direct Bitbucket API integration
  • 🎨 TUI Libraries - Rich terminal interfaces (ratatui, crossterm)
  • ⚡ Async - Non-blocking operations with tokio

Design Principles

  • Smart Force Push - Preserves review history while enabling safe rebases
  • Atomic Operations - All-or-nothing state changes
  • Conflict Detection - Early detection with resolution guidance
  • Graceful Degradation - Continue working when services are unavailable

🧪 Testing

# Run full test suite
cargo test -- --test-threads=1

# Tests cover:
# - Core stack management (40 tests)
# - Git operations and safety
# - Bitbucket integration  
# - CLI command functionality
# - Error handling and recovery

Test Coverage: 98 tests passing ✅

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.