# stacking-pr
[](https://badge.fury.io/py/stacking-pr)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A developer tool for managing clean commit history and modular PRs through a stacked workflow.
## Overview
`stacking-pr` helps developers maintain a clean git history by managing stacked (dependent) pull requests. This approach allows you to break down large features into smaller, focused, and easily reviewable changes while maintaining their dependencies.
## Features
- 🏗️ **Stacked Branches**: Create dependent branches that build on each other
- 🔄 **Smart Push**: Push entire stacks with proper dependency order
- 📝 **PR Management**: Automatically create and update pull requests using GitHub CLI
- 🎯 **Clean Merges**: Merge stacks in the correct order to maintain history
- 📊 **Visual Status**: See your entire stack structure at a glance
- 🔧 **Git Integration**: Works seamlessly with your existing git workflow
## How It Works
`stacking-pr` tracks your branch dependencies in a local `.stacking-pr.yml` file:
1. **Each branch knows its parent**: When you create a branch, it records what it's based on
2. **Commands respect hierarchy**: Operations happen in dependency order automatically
3. **Git stays in control**: We only run standard Git commands you could run manually
4. **PR descriptions are smart**: Automatically includes dependency information
Under the hood, `stacking-pr` runs standard Git commands:
- `git checkout -b` for branch creation
- `git push --force-with-lease` for safe force pushes
- `gh pr create` for PR management
Your Git history remains clean and linear, just as if you managed it manually.
## Installation
### From PyPI
```bash
pip install stacking-pr
```
### From Source
```bash
git clone https://github.com/hitesharora1997/stacking-pr.git
cd stacking-pr
pip install -e .
```
### Prerequisites
- Python 3.9+
- Git
- GitHub CLI (`gh`) - optional but recommended for PR management
## Quick Start
1. **Initialize your repository**:
```bash
stacking-pr init
```
2. **Create a new branch in your stack**:
```bash
stacking-pr create feature/api-base
```
3. **Create dependent branches**:
```bash
stacking-pr create feature/api-endpoints
stacking-pr create feature/api-tests
```
4. **Check your stack status**:
```bash
stacking-pr status
```
5. **Push your stack and create PRs**:
```bash
stacking-pr push --all --create-prs
```
## Getting Started Tutorial
This tutorial walks you through using `stacking-pr` to implement a user authentication feature as a series of stacked pull requests.
### Scenario
You're adding authentication to your application. Instead of one massive PR, you'll create:
1. Base authentication interfaces and types
2. JWT token implementation
3. User login endpoints
4. Tests and documentation
### Step 1: Setup
First, ensure you have the prerequisites:
```bash
# Check Git is installed
git --version
# Check GitHub CLI is installed (optional but recommended)
gh --version
# Install stacking-pr
pip install stacking-pr
```
Navigate to your project and initialize stacking-pr:
```bash
cd my-project
stacking-pr init
```
This creates a `.stacking-pr.yml` file to track your stacks.
### Step 2: Create the Base Branch
Start with the foundation - authentication interfaces:
```bash
# Create the first branch in your stack
stacking-pr create feature/auth-interfaces
# You're automatically switched to the new branch
# Now add your base authentication code
mkdir -p src/auth
echo "# Authentication interfaces" > src/auth/__init__.py
```
Create your interface files:
```python
# src/auth/interfaces.py
from abc import ABC, abstractmethod
from typing import Optional, Dict
class AuthProvider(ABC):
@abstractmethod
def authenticate(self, credentials: Dict) -> Optional[str]:
"""Authenticate user and return token"""
pass
class TokenValidator(ABC):
@abstractmethod
def validate(self, token: str) -> Optional[Dict]:
"""Validate token and return user info"""
pass
```
Commit your changes:
```bash
git add src/auth/
git commit -m "feat: add authentication interfaces
- Add AuthProvider abstract base class
- Add TokenValidator abstract base class
- Set up auth module structure"
```
### Step 3: Stack the Implementation
Now create a branch for the JWT implementation that builds on top:
```bash
# This creates a new branch based on feature/auth-interfaces
stacking-pr create feature/jwt-implementation
# Add your JWT implementation
cat > src/auth/jwt_provider.py << 'EOF'
import jwt
from typing import Optional, Dict
from .interfaces import AuthProvider, TokenValidator
class JWTProvider(AuthProvider, TokenValidator):
def __init__(self, secret: str):
self.secret = secret
def authenticate(self, credentials: Dict) -> Optional[str]:
# Implementation here
pass
def validate(self, token: str) -> Optional[Dict]:
# Implementation here
pass
EOF
```
Commit the implementation:
```bash
git add src/auth/jwt_provider.py
git commit -m "feat: implement JWT authentication provider
- Add JWTProvider class implementing both interfaces
- Support token generation and validation
- Configure with secret key"
```
### Step 4: Add API Endpoints
Create another stacked branch for the API layer:
```bash
stacking-pr create feature/auth-endpoints
# Add login endpoint
mkdir -p src/api
cat > src/api/auth.py << 'EOF'
from fastapi import APIRouter, Depends
from src.auth.jwt_provider import JWTProvider
router = APIRouter(prefix="/auth")
@router.post("/login")
async def login(username: str, password: str):
# Login implementation
pass
@router.get("/verify")
async def verify(token: str):
# Token verification
pass
EOF
```
Commit:
```bash
git add src/api/
git commit -m "feat: add authentication API endpoints
- Add /auth/login endpoint
- Add /auth/verify endpoint
- Integrate with JWTProvider"
```
### Step 5: Check Your Stack Status
View your stack structure:
```bash
stacking-pr status --verbose
```
Output:
```
📚 Stack Overview:
==================================================
main (base)
└── feature/auth-interfaces
└── feature/jwt-implementation
└── feature/auth-endpoints
📊 Branch Details:
--------------------------------------------------
feature/auth-interfaces:
Base: main
Commits: 1
feature/jwt-implementation:
Base: feature/auth-interfaces
Commits: 1
feature/auth-endpoints:
Base: feature/jwt-implementation
Commits: 1
💡 Tips:
• Create new branch: stacking-pr create <name>
• Push stack: stacking-pr push
• Merge stack: stacking-pr merge
```
### Step 6: Push and Create Pull Requests
Push your entire stack and create PRs:
```bash
# First, let's see what would happen (dry run)
stacking-pr push --all --create-prs --dry-run
# If everything looks good, push for real
stacking-pr push --all --create-prs
```
This will:
1. Push `feature/auth-interfaces` and create a PR against `main`
2. Push `feature/jwt-implementation` and create a PR against `feature/auth-interfaces`
3. Push `feature/auth-endpoints` and create a PR against `feature/jwt-implementation`
Each PR description will include:
- Commit messages from that branch
- Link to the base PR
- Clear dependency information
### Step 7: Handling Reviews and Updates
When reviewers request changes on the base PR:
```bash
# Switch to the branch that needs changes
git checkout feature/auth-interfaces
# Make the requested changes
echo "# Updated based on review" >> src/auth/interfaces.py
git add src/auth/interfaces.py
git commit -m "fix: address review comments on interfaces"
# Push just this branch
stacking-pr push
# The dependent branches may need rebasing
# stacking-pr will guide you through this
```
### Step 8: Adding Tests (New Branch in Stack)
Add tests as another layer:
```bash
# Make sure you're on the latest branch
git checkout feature/auth-endpoints
# Create test branch
stacking-pr create feature/auth-tests
# Add tests
mkdir -p tests/auth
cat > tests/auth/test_jwt.py << 'EOF'
def test_jwt_provider():
# Test implementation
pass
EOF
git add tests/
git commit -m "test: add authentication tests
- Test JWT token generation
- Test token validation
- Test API endpoints"
# Push the new branch
stacking-pr push --create-prs
```
### Step 9: Merging the Stack
Once all PRs are approved:
```bash
# Check PR status
stacking-pr status --prs
# Merge the entire stack in order
stacking-pr merge --cascade --delete-branches
```
This will:
1. Merge `feature/auth-interfaces` into `main`
2. Merge `feature/jwt-implementation` into `main`
3. Merge `feature/auth-endpoints` into `main`
4. Merge `feature/auth-tests` into `main`
5. Delete the feature branches (local and remote)
### Step 10: Stack Maintenance
If the main branch is updated while you're working:
```bash
# Update your local main
git checkout main
git pull
# Rebase your entire stack
stacking-pr rebase --all
# Force push all branches (safely with --force-with-lease)
stacking-pr push --all --force-with-lease
```
### Common Workflows
#### Split a Large Branch
```bash
# You realize feature/big-change is too large
git checkout feature/big-change
stacking-pr split --into 3
# Interactive prompt helps you organize commits
```
#### Insert a Branch in the Middle
```bash
# Need to add something between jwt-implementation and endpoints
git checkout feature/jwt-implementation
stacking-pr create feature/jwt-middleware
# Make changes
stacking-pr rebase --cascade # Updates branches above
```
#### Emergency Fix
```bash
# Need to fix something in the base while stack is in review
stacking-pr fix feature/auth-interfaces
# Guides you through fixing and rebasing dependent branches
```
### Pro Tips
1. **Commit Messages Matter**: Your first commit message becomes the PR title
2. **Keep Branches Small**: 100-300 lines is ideal for reviews
3. **Use Draft PRs**: `stacking-pr push --draft` while work is in progress
4. **Visualize Before Push**: Always run `status --verbose` before pushing
5. **Name Branches Clearly**: Use a consistent naming scheme like `feature/component-aspect`
### What's Next?
- Read about [advanced workflows](docs/advanced.md)
- Learn about [team collaboration](docs/team.md)
- Configure [custom templates](docs/templates.md)
- Set up [CI/CD integration](docs/ci-cd.md)
## Commands
### `init`
Initialize a repository for stacked PR workflow.
```bash
stacking-pr init [--force]
```
Options:
- `--force, -f`: Force initialization even if already initialized
### `create`
Create a new branch in the stack.
```bash
stacking-pr create <branch-name> [OPTIONS]
```
Options:
- `--base, -b`: Base branch for the new branch (defaults to current branch)
- `--checkout/--no-checkout`: Whether to checkout the new branch after creation
### `status`
Show the status of the current stack.
```bash
stacking-pr status [OPTIONS]
```
Options:
- `--verbose, -v`: Show detailed information about each branch
- `--prs`: Show associated pull request information
Example output:
```
📚 Stack Overview:
==================================================
main (base)
└── feature/api-base
├── feature/api-endpoints
└── feature/api-tests
```
### `push`
Push branches and optionally create/update pull requests.
```bash
stacking-pr push [OPTIONS]
```
Options:
- `--all, -a`: Push all branches in the stack
- `--create-prs`: Create pull requests for branches without them
- `--draft`: Create pull requests as drafts
### `rebase`
Rebase current branch or entire stack.
```bash
stacking-pr rebase [OPTIONS]
```
Options:
- `--stack, -s`: Rebase entire stack (otherwise just current branch)
- `--onto`: Branch to rebase onto (defaults to base branch from config)
- `--interactive, -i`: Interactive rebase (requires manual interaction)
### `merge`
Merge stacked branches in the correct order.
```bash
stacking-pr merge [OPTIONS]
```
Options:
- `--branch, -b`: Specific branch to merge (defaults to current branch)
- `--all`: Merge all branches in the stack
- `--delete-branches`: Delete branches after successful merge
## Workflow Example
Here's a typical workflow for implementing a new feature:
```bash
# Initialize the repo for stacked PRs
stacking-pr init
# Create base implementation
stacking-pr create feature/user-model
# ... make changes, commit ...
# Add API endpoints on top
stacking-pr create feature/user-api
# ... make changes, commit ...
# Add tests on top
stacking-pr create feature/user-tests
# ... make changes, commit ...
# View the stack
stacking-pr status --verbose
# Push everything and create PRs
stacking-pr push --all --create-prs
# After reviews, merge in order
stacking-pr merge --cascade --delete-branches
```
## Configuration
The tool creates a `.stacking-pr.yml` configuration file in your repository root. This file tracks:
- Stack structure and dependencies
- PR associations
- Default settings
Example configuration:
```yaml
version: "1.0"
stack:
feature/api-base:
base: main
pr_number: 123
feature/api-endpoints:
base: feature/api-base
pr_number: 124
settings:
base_branch: main
auto_create_prs: false
delete_after_merge: false
```
## Best Practices
1. **Keep branches focused**: Each branch should represent one logical change
2. **Write descriptive commit messages**: They'll be used for PR descriptions
3. **Update regularly**: Rebase your stack when the base branch updates
4. **Review in order**: Review PRs from bottom to top of the stack
5. **Merge in order**: Always merge from the base up to maintain history
## Troubleshooting
### GitHub CLI not found
Install the GitHub CLI and authenticate:
```bash
# Install
brew install gh # macOS
# or see: https://cli.github.com/
# Authenticate
gh auth login
```
### Conflicts during merge
1. Resolve conflicts in the bottom-most branch first
2. Rebase dependent branches after resolving
3. Push with `--force-with-lease`
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## License
MIT License - see [LICENSE](LICENSE) for details.
## Credits
Created by Hitesh Arora
Inspired by tools like [git-branchless](https://github.com/arxanas/git-branchless) and GitHub's stacked PR workflow.
Raw data
{
"_id": null,
"home_page": null,
"name": "stacking-pr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "git, github, pull-request, workflow, developer-tools, cli",
"author": null,
"author_email": "Hitesh Arora <hitesh.arora1997@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/86/be/2bc8c89db02045f35ab2f12f20b2d9c9890fc89b601a23b843ab15ef2fcc/stacking_pr-0.3.0.tar.gz",
"platform": null,
"description": "# stacking-pr\n\n[](https://badge.fury.io/py/stacking-pr)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA developer tool for managing clean commit history and modular PRs through a stacked workflow.\n\n## Overview\n\n`stacking-pr` helps developers maintain a clean git history by managing stacked (dependent) pull requests. This approach allows you to break down large features into smaller, focused, and easily reviewable changes while maintaining their dependencies.\n\n## Features\n\n- \ud83c\udfd7\ufe0f **Stacked Branches**: Create dependent branches that build on each other\n- \ud83d\udd04 **Smart Push**: Push entire stacks with proper dependency order\n- \ud83d\udcdd **PR Management**: Automatically create and update pull requests using GitHub CLI\n- \ud83c\udfaf **Clean Merges**: Merge stacks in the correct order to maintain history\n- \ud83d\udcca **Visual Status**: See your entire stack structure at a glance\n- \ud83d\udd27 **Git Integration**: Works seamlessly with your existing git workflow\n\n## How It Works\n\n`stacking-pr` tracks your branch dependencies in a local `.stacking-pr.yml` file:\n\n1. **Each branch knows its parent**: When you create a branch, it records what it's based on\n2. **Commands respect hierarchy**: Operations happen in dependency order automatically\n3. **Git stays in control**: We only run standard Git commands you could run manually\n4. **PR descriptions are smart**: Automatically includes dependency information\n\nUnder the hood, `stacking-pr` runs standard Git commands:\n- `git checkout -b` for branch creation \n- `git push --force-with-lease` for safe force pushes\n- `gh pr create` for PR management\n\nYour Git history remains clean and linear, just as if you managed it manually.\n\n## Installation\n\n### From PyPI\n\n```bash\npip install stacking-pr\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/hitesharora1997/stacking-pr.git\ncd stacking-pr\npip install -e .\n```\n\n### Prerequisites\n\n- Python 3.9+\n- Git\n- GitHub CLI (`gh`) - optional but recommended for PR management\n\n## Quick Start\n\n1. **Initialize your repository**:\n ```bash\n stacking-pr init\n ```\n\n2. **Create a new branch in your stack**:\n ```bash\n stacking-pr create feature/api-base\n ```\n\n3. **Create dependent branches**:\n ```bash\n stacking-pr create feature/api-endpoints\n stacking-pr create feature/api-tests\n ```\n\n4. **Check your stack status**:\n ```bash\n stacking-pr status\n ```\n\n5. **Push your stack and create PRs**:\n ```bash\n stacking-pr push --all --create-prs\n ```\n\n## Getting Started Tutorial\n\nThis tutorial walks you through using `stacking-pr` to implement a user authentication feature as a series of stacked pull requests.\n\n### Scenario\nYou're adding authentication to your application. Instead of one massive PR, you'll create:\n1. Base authentication interfaces and types\n2. JWT token implementation\n3. User login endpoints\n4. Tests and documentation\n\n### Step 1: Setup\n\nFirst, ensure you have the prerequisites:\n\n```bash\n# Check Git is installed\ngit --version\n\n# Check GitHub CLI is installed (optional but recommended)\ngh --version\n\n# Install stacking-pr\npip install stacking-pr\n```\n\nNavigate to your project and initialize stacking-pr:\n\n```bash\ncd my-project\nstacking-pr init\n```\n\nThis creates a `.stacking-pr.yml` file to track your stacks.\n\n### Step 2: Create the Base Branch\n\nStart with the foundation - authentication interfaces:\n\n```bash\n# Create the first branch in your stack\nstacking-pr create feature/auth-interfaces\n\n# You're automatically switched to the new branch\n# Now add your base authentication code\nmkdir -p src/auth\necho \"# Authentication interfaces\" > src/auth/__init__.py\n```\n\nCreate your interface files:\n\n```python\n# src/auth/interfaces.py\nfrom abc import ABC, abstractmethod\nfrom typing import Optional, Dict\n\nclass AuthProvider(ABC):\n @abstractmethod\n def authenticate(self, credentials: Dict) -> Optional[str]:\n \"\"\"Authenticate user and return token\"\"\"\n pass\n\nclass TokenValidator(ABC):\n @abstractmethod\n def validate(self, token: str) -> Optional[Dict]:\n \"\"\"Validate token and return user info\"\"\"\n pass\n```\n\nCommit your changes:\n\n```bash\ngit add src/auth/\ngit commit -m \"feat: add authentication interfaces\n\n- Add AuthProvider abstract base class\n- Add TokenValidator abstract base class\n- Set up auth module structure\"\n```\n\n### Step 3: Stack the Implementation\n\nNow create a branch for the JWT implementation that builds on top:\n\n```bash\n# This creates a new branch based on feature/auth-interfaces\nstacking-pr create feature/jwt-implementation\n\n# Add your JWT implementation\ncat > src/auth/jwt_provider.py << 'EOF'\nimport jwt\nfrom typing import Optional, Dict\nfrom .interfaces import AuthProvider, TokenValidator\n\nclass JWTProvider(AuthProvider, TokenValidator):\n def __init__(self, secret: str):\n self.secret = secret\n \n def authenticate(self, credentials: Dict) -> Optional[str]:\n # Implementation here\n pass\n \n def validate(self, token: str) -> Optional[Dict]:\n # Implementation here\n pass\nEOF\n```\n\nCommit the implementation:\n\n```bash\ngit add src/auth/jwt_provider.py\ngit commit -m \"feat: implement JWT authentication provider\n\n- Add JWTProvider class implementing both interfaces\n- Support token generation and validation\n- Configure with secret key\"\n```\n\n### Step 4: Add API Endpoints\n\nCreate another stacked branch for the API layer:\n\n```bash\nstacking-pr create feature/auth-endpoints\n\n# Add login endpoint\nmkdir -p src/api\ncat > src/api/auth.py << 'EOF'\nfrom fastapi import APIRouter, Depends\nfrom src.auth.jwt_provider import JWTProvider\n\nrouter = APIRouter(prefix=\"/auth\")\n\n@router.post(\"/login\")\nasync def login(username: str, password: str):\n # Login implementation\n pass\n\n@router.get(\"/verify\")\nasync def verify(token: str):\n # Token verification\n pass\nEOF\n```\n\nCommit:\n\n```bash\ngit add src/api/\ngit commit -m \"feat: add authentication API endpoints\n\n- Add /auth/login endpoint\n- Add /auth/verify endpoint\n- Integrate with JWTProvider\"\n```\n\n### Step 5: Check Your Stack Status\n\nView your stack structure:\n\n```bash\nstacking-pr status --verbose\n```\n\nOutput:\n```\n\ud83d\udcda Stack Overview:\n==================================================\nmain (base)\n\u2514\u2500\u2500 feature/auth-interfaces\n \u2514\u2500\u2500 feature/jwt-implementation\n \u2514\u2500\u2500 feature/auth-endpoints\n\n\ud83d\udcca Branch Details:\n--------------------------------------------------\n\nfeature/auth-interfaces:\n Base: main\n Commits: 1\n\nfeature/jwt-implementation:\n Base: feature/auth-interfaces\n Commits: 1\n\nfeature/auth-endpoints:\n Base: feature/jwt-implementation\n Commits: 1\n\n\ud83d\udca1 Tips:\n \u2022 Create new branch: stacking-pr create <name>\n \u2022 Push stack: stacking-pr push\n \u2022 Merge stack: stacking-pr merge\n```\n\n### Step 6: Push and Create Pull Requests\n\nPush your entire stack and create PRs:\n\n```bash\n# First, let's see what would happen (dry run)\nstacking-pr push --all --create-prs --dry-run\n\n# If everything looks good, push for real\nstacking-pr push --all --create-prs\n```\n\nThis will:\n1. Push `feature/auth-interfaces` and create a PR against `main`\n2. Push `feature/jwt-implementation` and create a PR against `feature/auth-interfaces`\n3. Push `feature/auth-endpoints` and create a PR against `feature/jwt-implementation`\n\nEach PR description will include:\n- Commit messages from that branch\n- Link to the base PR\n- Clear dependency information\n\n### Step 7: Handling Reviews and Updates\n\nWhen reviewers request changes on the base PR:\n\n```bash\n# Switch to the branch that needs changes\ngit checkout feature/auth-interfaces\n\n# Make the requested changes\necho \"# Updated based on review\" >> src/auth/interfaces.py\ngit add src/auth/interfaces.py\ngit commit -m \"fix: address review comments on interfaces\"\n\n# Push just this branch\nstacking-pr push\n\n# The dependent branches may need rebasing\n# stacking-pr will guide you through this\n```\n\n### Step 8: Adding Tests (New Branch in Stack)\n\nAdd tests as another layer:\n\n```bash\n# Make sure you're on the latest branch\ngit checkout feature/auth-endpoints\n\n# Create test branch\nstacking-pr create feature/auth-tests\n\n# Add tests\nmkdir -p tests/auth\ncat > tests/auth/test_jwt.py << 'EOF'\ndef test_jwt_provider():\n # Test implementation\n pass\nEOF\n\ngit add tests/\ngit commit -m \"test: add authentication tests\n\n- Test JWT token generation\n- Test token validation\n- Test API endpoints\"\n\n# Push the new branch\nstacking-pr push --create-prs\n```\n\n### Step 9: Merging the Stack\n\nOnce all PRs are approved:\n\n```bash\n# Check PR status\nstacking-pr status --prs\n\n# Merge the entire stack in order\nstacking-pr merge --cascade --delete-branches\n```\n\nThis will:\n1. Merge `feature/auth-interfaces` into `main`\n2. Merge `feature/jwt-implementation` into `main`\n3. Merge `feature/auth-endpoints` into `main`\n4. Merge `feature/auth-tests` into `main`\n5. Delete the feature branches (local and remote)\n\n### Step 10: Stack Maintenance\n\nIf the main branch is updated while you're working:\n\n```bash\n# Update your local main\ngit checkout main\ngit pull\n\n# Rebase your entire stack\nstacking-pr rebase --all\n\n# Force push all branches (safely with --force-with-lease)\nstacking-pr push --all --force-with-lease\n```\n\n### Common Workflows\n\n#### Split a Large Branch\n```bash\n# You realize feature/big-change is too large\ngit checkout feature/big-change\nstacking-pr split --into 3\n# Interactive prompt helps you organize commits\n```\n\n#### Insert a Branch in the Middle\n```bash\n# Need to add something between jwt-implementation and endpoints\ngit checkout feature/jwt-implementation\nstacking-pr create feature/jwt-middleware\n# Make changes\nstacking-pr rebase --cascade # Updates branches above\n```\n\n#### Emergency Fix\n```bash\n# Need to fix something in the base while stack is in review\nstacking-pr fix feature/auth-interfaces\n# Guides you through fixing and rebasing dependent branches\n```\n\n### Pro Tips\n\n1. **Commit Messages Matter**: Your first commit message becomes the PR title\n2. **Keep Branches Small**: 100-300 lines is ideal for reviews\n3. **Use Draft PRs**: `stacking-pr push --draft` while work is in progress\n4. **Visualize Before Push**: Always run `status --verbose` before pushing\n5. **Name Branches Clearly**: Use a consistent naming scheme like `feature/component-aspect`\n\n### What's Next?\n\n- Read about [advanced workflows](docs/advanced.md)\n- Learn about [team collaboration](docs/team.md)\n- Configure [custom templates](docs/templates.md)\n- Set up [CI/CD integration](docs/ci-cd.md)\n\n## Commands\n\n### `init`\nInitialize a repository for stacked PR workflow.\n\n```bash\nstacking-pr init [--force]\n```\n\nOptions:\n- `--force, -f`: Force initialization even if already initialized\n\n### `create`\nCreate a new branch in the stack.\n\n```bash\nstacking-pr create <branch-name> [OPTIONS]\n```\n\nOptions:\n- `--base, -b`: Base branch for the new branch (defaults to current branch)\n- `--checkout/--no-checkout`: Whether to checkout the new branch after creation\n\n### `status`\nShow the status of the current stack.\n\n```bash\nstacking-pr status [OPTIONS]\n```\n\nOptions:\n- `--verbose, -v`: Show detailed information about each branch\n- `--prs`: Show associated pull request information\n\nExample output:\n```\n\ud83d\udcda Stack Overview:\n==================================================\nmain (base)\n\u2514\u2500\u2500 feature/api-base\n \u251c\u2500\u2500 feature/api-endpoints\n \u2514\u2500\u2500 feature/api-tests\n```\n\n### `push`\nPush branches and optionally create/update pull requests.\n\n```bash\nstacking-pr push [OPTIONS]\n```\n\nOptions:\n- `--all, -a`: Push all branches in the stack\n- `--create-prs`: Create pull requests for branches without them\n- `--draft`: Create pull requests as drafts\n\n### `rebase`\nRebase current branch or entire stack.\n\n```bash\nstacking-pr rebase [OPTIONS]\n```\n\nOptions:\n- `--stack, -s`: Rebase entire stack (otherwise just current branch)\n- `--onto`: Branch to rebase onto (defaults to base branch from config)\n- `--interactive, -i`: Interactive rebase (requires manual interaction)\n\n### `merge`\nMerge stacked branches in the correct order.\n\n```bash\nstacking-pr merge [OPTIONS]\n```\n\nOptions:\n- `--branch, -b`: Specific branch to merge (defaults to current branch)\n- `--all`: Merge all branches in the stack\n- `--delete-branches`: Delete branches after successful merge\n\n## Workflow Example\n\nHere's a typical workflow for implementing a new feature:\n\n```bash\n# Initialize the repo for stacked PRs\nstacking-pr init\n\n# Create base implementation\nstacking-pr create feature/user-model\n# ... make changes, commit ...\n\n# Add API endpoints on top\nstacking-pr create feature/user-api\n# ... make changes, commit ...\n\n# Add tests on top\nstacking-pr create feature/user-tests\n# ... make changes, commit ...\n\n# View the stack\nstacking-pr status --verbose\n\n# Push everything and create PRs\nstacking-pr push --all --create-prs\n\n# After reviews, merge in order\nstacking-pr merge --cascade --delete-branches\n```\n\n## Configuration\n\nThe tool creates a `.stacking-pr.yml` configuration file in your repository root. This file tracks:\n\n- Stack structure and dependencies\n- PR associations\n- Default settings\n\nExample configuration:\n```yaml\nversion: \"1.0\"\nstack:\n feature/api-base:\n base: main\n pr_number: 123\n feature/api-endpoints:\n base: feature/api-base\n pr_number: 124\nsettings:\n base_branch: main\n auto_create_prs: false\n delete_after_merge: false\n```\n\n## Best Practices\n\n1. **Keep branches focused**: Each branch should represent one logical change\n2. **Write descriptive commit messages**: They'll be used for PR descriptions\n3. **Update regularly**: Rebase your stack when the base branch updates\n4. **Review in order**: Review PRs from bottom to top of the stack\n5. **Merge in order**: Always merge from the base up to maintain history\n\n## Troubleshooting\n\n### GitHub CLI not found\nInstall the GitHub CLI and authenticate:\n```bash\n# Install\nbrew install gh # macOS\n# or see: https://cli.github.com/\n\n# Authenticate\ngh auth login\n```\n\n### Conflicts during merge\n1. Resolve conflicts in the bottom-most branch first\n2. Rebase dependent branches after resolving\n3. Push with `--force-with-lease`\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Credits\n\nCreated by Hitesh Arora\n\nInspired by tools like [git-branchless](https://github.com/arxanas/git-branchless) and GitHub's stacked PR workflow.\n",
"bugtrack_url": null,
"license": null,
"summary": "A developer tool for managing clean commit history and modular PRs",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/hitesharora1997/stacking-pr#readme",
"Homepage": "https://github.com/hitesharora1997/stacking-pr",
"Issues": "https://github.com/hitesharora1997/stacking-pr/issues",
"Repository": "https://github.com/hitesharora1997/stacking-pr"
},
"split_keywords": [
"git",
" github",
" pull-request",
" workflow",
" developer-tools",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "40633f60ba89cbf8bb83a92f0a629f749d894511779ac55c5fee557c3348cae0",
"md5": "d632ea8eaaf870a511fcb6921d9ac16a",
"sha256": "40657f009e4e2c879124ba57b6416d9c05582ab883e158b2864fdee59390b5c7"
},
"downloads": -1,
"filename": "stacking_pr-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d632ea8eaaf870a511fcb6921d9ac16a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21954,
"upload_time": "2025-07-23T06:44:47",
"upload_time_iso_8601": "2025-07-23T06:44:47.707630Z",
"url": "https://files.pythonhosted.org/packages/40/63/3f60ba89cbf8bb83a92f0a629f749d894511779ac55c5fee557c3348cae0/stacking_pr-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "86be2bc8c89db02045f35ab2f12f20b2d9c9890fc89b601a23b843ab15ef2fcc",
"md5": "67c4ce92f63cccd31dfd8d0555c15364",
"sha256": "3831a6c26b3253223e05e406a92aad29ad477b29880a0a2d6abcb4f90c98fbd3"
},
"downloads": -1,
"filename": "stacking_pr-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "67c4ce92f63cccd31dfd8d0555c15364",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 25274,
"upload_time": "2025-07-23T06:44:49",
"upload_time_iso_8601": "2025-07-23T06:44:49.305427Z",
"url": "https://files.pythonhosted.org/packages/86/be/2bc8c89db02045f35ab2f12f20b2d9c9890fc89b601a23b843ab15ef2fcc/stacking_pr-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 06:44:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hitesharora1997",
"github_project": "stacking-pr#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "stacking-pr"
}
JSON
