Flow beyond branches; stream your releases
Git Stream is a sophisticated git workflow system that extends beyond standard git flow to support multiple simultaneous releases, epic-based feature organization, and DTAP environments.
Create and manage multiple release branches at the same time, each with different feature sets. Perfect for parallel environment deployments and client-specific versions.
No complex parameters to remember - Git Stream prompts you for what it needs:
# Simple, guided workflow
gstr feature start # Prompts for name, epic, base branch
gstr release start # Interactive feature/epic selection menu
gstr hotfix start # Prompts for name, automatically detects baseGroup related features into epics for better organization and release management. Completed epics appear as selectable units during release creation.
- Remote Mode (with PRs): Pull request-based workflow for GitHub/BitBucket with code review
- Remote Mode (PR-less): Direct merge to remote branches, synced via push/pull
- Local Mode: Direct merge workflow for local-only repositories
- Auto-detection: Automatically detects and configures based on your repository
Configure credentials once in ~/.gitstream/config.json and use them across all your repositories. No per-project setup needed.
Built-in deployment targeting for Development, Test, Acceptance, and Production environments via git-native deployment tags.
Automatic tracking of merge dependencies between branches. When you merge one branch into another, Git Stream records the relationship and ensures dependencies are included in releases.
Automatic synchronization keeps develop aligned with the main production baseline. Before finishing features/epics, Git Stream syncs main → develop, preventing drift and ensuring develop is always a valid superset of production code. After releases, main is merged back to develop automatically. See Stop the Drifting Develop for technical details.
- Git hooks prevent direct git operations that bypass workflow
- Comprehensive validation before all operations
- Protected branch enforcement
- Circular dependency prevention
- Automatic baseline synchronization to prevent branch drift
# Via Composer (global)
composer global require lengthofrope/gitstream
# Ensure Composer global bin is in your PATH
export PATH="$HOME/.composer/vendor/bin:$PATH"Using install script:
curl -fsSL https://raw.githubusercontent.com/lengthofrope/gitstream/main/scripts/install.sh | bashUsing PHAR:
curl -L https://github.com/lengthofrope/gitstream/releases/latest/download/gstr.phar -o gstr
chmod +x gstr
sudo mv gstr /usr/local/bin/From source:
git clone https://github.com/lengthofrope/gitstream.git
cd gitstream
composer install --no-dev --optimize-autoloader
sudo ln -s $(pwd)/bin/gstr /usr/local/bin/gstrFor remote repositories (GitHub/BitBucket):
cd your-project
gstr init
# Auto-detects provider from origin URL
# Configure credentials (once per user)
gstr config --global credentials.github.token ghp_your_token_here
# or for BitBucket:
gstr config --global credentials.bitbucket.username your-username
gstr config --global credentials.bitbucket.password your-app-passwordFor local repositories:
cd your-project
gstr init
# Choose "Continue with local workflow"
# No credentials needed - works entirely offline# Start a feature
gstr feature start
# → Prompts: Feature name, epic selection (optional)
# Make commits
gstr commit
# → Prompts: Commit message (automatically tagged)
# Finish feature
gstr feature finish
# → Creates PR (remote mode) or merges directly (local mode)
# Create a release
gstr release start
# → Prompts: Version, interactive feature/epic selection
# Finish release
gstr release finish
# → Deploys to production
# Synchronize repository
gstr sync
# → Processes merged PRs, updates deployment tags| Feature | Git Flow | Git Stream |
|---|---|---|
| Release Model | Single release at a time | Multiple simultaneous releases |
| Command Interface | Parameter-heavy commands | Interactive prompts |
| Workflow Mode | Remote-only assumption | Auto-detects local/remote modes |
| Credential Management | Per-project setup | Global shared credentials |
| Feature Organization | Flat feature branches | Hierarchical epics + features |
| Dependency Tracking | Manual management | Automatic tracking + validation |
| Drift Prevention | Manual synchronization | Automatic baseline synchronization |
| Safety Features | Basic git operations | Comprehensive validation + hooks |
| Repository Structure | External directories | Git-native .git/gitstream/ |
Choose Git Stream when:
- Multiple releases need preparation simultaneously
- Team works across multiple repositories frequently
- DTAP environments require parallel release management
- Feature organization and epic grouping add value
- Safety and validation are priorities
- Mixed local/remote development workflows exist
Stick with Git Flow when:
- Simple, linear development workflow
- Single release preparation sufficient
- Team prefers command-line parameter control
- Minimal tooling dependency required
Git Stream implements a sophisticated branching model supporting hierarchical feature development, multiple simultaneous releases, and both local and remote workflows.
gitGraph
commit id: "Initial"
branch develop
checkout develop
commit id: "Setup"
checkout main
branch epic/AUTH-123
commit id: "Epic: Auth Setup"
branch epic-feature/AUTH-123-login-form
commit id: "Login UI"
commit id: "Validation"
checkout epic/AUTH-123
branch epic-feature/AUTH-123-oauth
commit id: "OAuth Setup"
commit id: "Provider Config"
checkout epic/AUTH-123
merge epic-feature/AUTH-123-login-form
commit id: "Merge Login"
merge epic-feature/AUTH-123-oauth
commit id: "Merge OAuth"
checkout main
branch epic/PAY-456
commit id: "Epic: Payment"
branch epic-feature/PAY-456-stripe
commit id: "Stripe API"
commit id: "Payment UI"
checkout main
branch feature/quick-fix
commit id: "Standalone Fix"
checkout develop
merge main tag: "sync: baseline update"
commit id: "Sync from main"
merge epic/AUTH-123
commit id: "Epic Auth Complete"
merge feature/quick-fix
commit id: "Quick Fix Merged"
checkout epic/PAY-456
merge epic-feature/PAY-456-stripe
commit id: "Merge Stripe"
checkout develop
merge main tag: "sync: baseline update"
commit id: "Sync before epic merge"
merge epic/PAY-456
commit id: "Epic Payment Complete"
checkout main
branch release/v1.5.0
merge feature/quick-fix
merge epic/AUTH-123
commit id: "Release: v1.5.0"
checkout main
branch release/v2.0.0
merge epic/PAY-456
commit id: "Release: v2.0.0"
checkout main
merge release/v1.5.0
commit id: "v1.5.0 Deployed"
checkout develop
merge main tag: "sync: after release"
commit id: "Sync main→develop"
checkout main
branch hotfix/security-fix
commit id: "Security Patch"
checkout main
merge hotfix/security-fix
commit id: "Hotfix Applied"
checkout develop
merge main tag: "sync: after hotfix"
commit id: "Sync hotfix"
merge hotfix/security-fix
commit id: "Hotfix direct merge"
checkout release/v2.0.0
merge hotfix/security-fix
commit id: "Hotfix to release"
checkout main
merge release/v2.0.0
commit id: "v2.0.0 Deployed"
checkout develop
merge main tag: "sync: after release"
commit id: "Final sync from main"
Git Stream provides 13 commands for complete workflow management:
init- Initialize Git Stream in a repositoryconfig- Manage configuration settingsstatus- Show repository statusfeature- Feature development workflowepic- Epic-based feature organizationrelease- Release managementhotfix- Hotfix workflowcommit- Safe commit wrappermerge- Safe branch merging with validationsync- Repository synchronizationclean- Branch cleanupmode- Workflow mode managementdeploy- DTAP deployment tag management
See the Command Reference for complete documentation.
- Command Cheat Sheet - Quick reference for common operations
- Configuration Guide - Setup and configuration details
- Workflow Modes - Remote vs Local workflow documentation
- Project Structure - Code organization and dependencies
- Deployment Tags - DTAP deployment targeting system
- Drift Prevention - Technical deep-dive on automatic baseline synchronization
- Release Commands - Start, finish, add, remove, list
- Feature Commands - Feature development workflow
- Epic Commands - Epic-based organization
- Release Add - Add features/epics to releases
- Release Remove - Remove features/epics from releases
- PHP 8.4+ with extensions: json, mbstring, curl
- Git 2.20+ for modern git operations
- Composer for dependency management
- Internet connection (for remote mode operations)
- GitHub or BitBucket account with API access (for PR mode)
Contributions are welcome! This project follows SOLID principles and modern PHP practices. All contributions must include tests and follow the established code style.
# Setup development environment
git clone https://github.com/lengthofrope/gitstream.git
cd gitstream
make dev-setup
# Run tests
make test
# Run quality checks
make qualityMIT License - see LICENSE file for details.
See CHANGELOG.md for version history and release notes.
"Hope is a good thing, maybe the best of things, and no good thing ever dies." - Like hope in Shawshank, Git Stream provides a better way forward for git workflows.