cmd

Overview ¶

Package cmd implements the command-line interface for Hitch, a Git workflow manager for multi-environment development.

Overview ¶

This package provides the complete CLI implementation using the Cobra framework, with commands for managing feature branch promotions across multiple deployment environments (dev, qa, staging, production, etc.).

Core Commands ¶

The package implements these primary commands:

• init: Initialize a new Hitch repository with environments
• status: Display current environment status and branch promotions
• validate: Validate hitch.json configuration file
• promote: Promote a feature branch to an environment
• demote: Remove a feature branch from an environment
• rebuild: Rebuild an environment branch from base + features
• release: Merge an environment to the base branch (e.g., dev → main)
• cleanup: Remove merged branches that are no longer needed
• lock: Lock an environment to prevent concurrent modifications
• unlock: Unlock an environment to allow modifications
• recover: Recover from stale locks or crashed operations
• hook: Generate hook commands for git hook integration
• install: Install Hitch binary to system PATH
• install-hooks: Install git hooks for automatic validation

Command Patterns ¶

Commands follow consistent patterns for user experience:

// Promote: hitch promote <branch> to <environment>
hitch promote feature/login to dev

// Demote: hitch demote <branch> from <environment>
hitch demote feature/login from dev

// Rebuild: hitch rebuild <environment>
hitch rebuild dev

// Release: hitch release <environment>
hitch release dev

Safety Mechanisms ¶

All commands implement multiple safety layers:

• Temp Branch Testing: Operations are tested in temporary branches before actual execution (via safety.TempBranchTester)
• Lock Management: Prevents concurrent environment modifications via metadata.LockManager
• Panic Recovery: Automatic recovery from crashes with state restoration
• Validation: Comprehensive pre-flight checks before any git operations

Global Flags ¶

All commands support these global flags:

• --verbose, -v: Enable verbose output for debugging
• --no-color: Disable colored output for CI/CD environments

Command-Specific Flags ¶

Common command-specific flags include:

• promote/demote: --no-rebuild (skip automatic rebuild)
• rebuild: --dry-run (preview changes), --force (bypass lock checks)
• cleanup: --dry-run (preview cleanup), --force (skip eligibility checks)
• lock: --reason (provide lock justification)
• unlock: --force (force unlock even if not lock owner)
• status: --env (filter by environment), --json (JSON output), --stale (show stale branches)

Testing ¶

The package includes comprehensive test coverage with:

• Unit tests for individual commands (promote_test.go, cleanup_release_test.go)
• Integration tests for complex workflows (integration_edge_cases_test.go)
• Behavioral tests for user-facing scenarios (behavioral_test.go)
• Helper and error path tests (helpers_errors_test.go, status_lock_test.go)

All tests run in isolated environments to ensure reproducibility.

Architecture ¶

Commands follow a consistent execution pattern:

1. Parse and validate user input (args, flags)
2. Load and validate repository state
3. Load metadata from hitch-metadata branch
4. Acquire necessary locks via LockManager
5. Test operations in temp branches (TempBranchTester)
6. Execute hooks if configured (HookExecutor)
7. Perform actual git operations
8. Update metadata and commit changes
9. Release locks and cleanup
10. Display user-friendly output

Error Handling ¶

Commands use colored, user-friendly error messages:

• ✓ Green checkmarks for successful operations
• ⚠ Yellow warnings for non-blocking issues
• ❌ Red X marks for errors and failures

Example output:

✓ Successfully tested merge of feature/login into dev
✓ Added feature/login to dev feature list
✓ Updated metadata
⚠ Skipped rebuild (use 'hitch rebuild dev' to rebuild)

Dependencies ¶

The package coordinates multiple internal packages:

• internal/git: Git repository operations
• internal/metadata: Metadata management on orphan branch
• internal/safety: Safe operation testing
• internal/validation: Input and state validation
• internal/hooks: Hook execution
• internal/security: Input sanitization

Example Usage ¶

Basic workflow for promoting a feature:

// Initialize Hitch in a repository
hitch init --environments dev,qa,staging,prod --base main

// Promote feature to dev
hitch promote feature/login to dev

// Check status
hitch status

// Rebuild dev environment
hitch rebuild dev

// Promote to qa after testing
hitch promote feature/login to qa
hitch rebuild qa

// Release to main when ready
hitch release qa

// Cleanup merged branches
hitch cleanup --dry-run  // Preview
hitch cleanup            // Execute