📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,246 @@
|
||||
---
|
||||
name: gitbutler-stacks
|
||||
description: This skill should be used when creating stacks, dependent branches, or when "stack", "stacked branches", "anchor", "--anchor", "but branch new -a", "create dependent branch", or "break feature into PRs" are mentioned with GitButler. Covers anchor-based stacking for dependent features and reviewable PR breakdown.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
author: outfitter
|
||||
category: version-control
|
||||
related-skills:
|
||||
- gitbutler-virtual-branches
|
||||
- gitbutler-complete-branch
|
||||
- gitbutler-multi-agent
|
||||
---
|
||||
|
||||
# GitButler Stacks
|
||||
|
||||
Dependent branches → anchor-based stacking → reviewable chunks.
|
||||
|
||||
<when_to_use>
|
||||
|
||||
- Sequential dependencies (e.g., refactor → API → frontend)
|
||||
- Large features broken into reviewable chunks
|
||||
- Granular code review (approve/merge early phases independently)
|
||||
- Post-hoc stack organization after exploratory coding
|
||||
|
||||
NOT for: independent parallel features (use virtual branches), projects using Graphite stacking
|
||||
|
||||
</when_to_use>
|
||||
|
||||
## Stacked vs Virtual Branches
|
||||
|
||||
| Type | Use Case | Dependencies |
|
||||
|------|----------|--------------|
|
||||
| **Virtual** | Independent, unrelated work | None — parallel |
|
||||
| **Stacked** | Sequential dependencies | Each builds on parent |
|
||||
|
||||
Stacked branches = virtual branches split into dependent sequence.
|
||||
Default: Virtual branches are stacks of one.
|
||||
|
||||
## Creating Stacks
|
||||
|
||||
```bash
|
||||
# Base branch (no anchor)
|
||||
but branch new base-feature
|
||||
|
||||
# Stacked branch (--anchor specifies parent)
|
||||
but branch new child-feature --anchor base-feature
|
||||
|
||||
# Third level
|
||||
but branch new grandchild-feature --anchor child-feature
|
||||
```
|
||||
|
||||
**Result:** `base-feature` ← `child-feature` ← `grandchild-feature`
|
||||
|
||||
**Short form:** `-a` instead of `--anchor`
|
||||
|
||||
```bash
|
||||
but branch new child -a parent
|
||||
```
|
||||
|
||||
## Stack Patterns
|
||||
|
||||
Common patterns: feature dependency chains, refactoring sequences, deep stacks.
|
||||
|
||||
**Example - Feature Dependency:**
|
||||
|
||||
```bash
|
||||
but branch new auth-core
|
||||
but branch new auth-oauth --anchor auth-core
|
||||
but branch new auth-social --anchor auth-oauth
|
||||
```
|
||||
|
||||
See `references/patterns.md` for detailed patterns with commit examples.
|
||||
|
||||
## Post-Hoc Stack Organization
|
||||
|
||||
Convert independent branches into a stack by recreating with correct anchors:
|
||||
|
||||
1. Create new branch with `--anchor` pointing to intended parent
|
||||
2. Move commits with `but rub <sha> <new-branch>`
|
||||
3. Delete original branch
|
||||
|
||||
See `references/reorganization.md` for detailed workflows.
|
||||
|
||||
## Publishing Stacks
|
||||
|
||||
### Using CLI (Preferred)
|
||||
|
||||
```bash
|
||||
# Push and create PR for a branch
|
||||
but push dependent-feature
|
||||
but pr new dependent-feature
|
||||
|
||||
# Push all unpushed branches
|
||||
but push
|
||||
```
|
||||
|
||||
`but push` + `but pr new` handles:
|
||||
- Pushing branches to remote
|
||||
- Creating PRs with correct base branches
|
||||
- Updating existing PRs if already created
|
||||
|
||||
### Using GitHub CLI (Alternative)
|
||||
|
||||
```bash
|
||||
# Push branches
|
||||
git push -u origin base-feature
|
||||
git push -u origin dependent-feature
|
||||
|
||||
# Create PRs with correct base branches
|
||||
gh pr create --base main --head base-feature \
|
||||
--title "feat: base feature" \
|
||||
--body "First in stack"
|
||||
|
||||
gh pr create --base base-feature --head dependent-feature \
|
||||
--title "feat: dependent feature" \
|
||||
--body "Depends on base-feature PR"
|
||||
```
|
||||
|
||||
### GitHub Settings
|
||||
|
||||
- Enable automatic branch deletion after merge
|
||||
- Use **Merge** strategy (recommended) — no force pushes needed
|
||||
- Merge bottom-to-top (sequential order)
|
||||
|
||||
## Conflict Handling in Stacks
|
||||
|
||||
GitButler resolves conflicts **per-commit** during rebase:
|
||||
|
||||
1. When base branch updates, dependent commits rebase automatically
|
||||
2. Conflicted commits marked but don't block other commits
|
||||
3. Resolve conflicts per affected commit
|
||||
4. Partial resolution can be saved and continued later
|
||||
|
||||
```bash
|
||||
# Update base (may trigger rebases in stack)
|
||||
but pull
|
||||
|
||||
# Check which commits have conflicts
|
||||
but status
|
||||
|
||||
# Resolve in editor, GitButler auto-detects resolution
|
||||
```
|
||||
|
||||
**Unlike git rebase:** Remaining commits continue rebasing even if some conflict.
|
||||
|
||||
## Stack Reorganization
|
||||
|
||||
Key operations for restructuring stacks:
|
||||
|
||||
| Operation | Command |
|
||||
|-----------|---------|
|
||||
| Squash commits | `but squash <branch>` or `but rub <newer> <older>` |
|
||||
| Move commit | `but rub <sha> <target-branch>` |
|
||||
| Split branch | Create anchored branch, move commits |
|
||||
|
||||
See `references/reorganization.md` for detailed examples.
|
||||
|
||||
## Stack Navigation
|
||||
|
||||
**Note:** Virtual branches don't need checkout — all branches active simultaneously.
|
||||
|
||||
```bash
|
||||
# View full stack structure
|
||||
but status
|
||||
|
||||
# Work on any branch directly (no checkout needed)
|
||||
but commit base-feature -m "update base"
|
||||
but commit dependent-feature -m "update dependent"
|
||||
|
||||
# Inspect a specific branch
|
||||
but show dependent-feature
|
||||
|
||||
# JSON for programmatic analysis
|
||||
but show dependent-feature --json | jq '.commits[] | .id'
|
||||
```
|
||||
|
||||
<rules>
|
||||
|
||||
ALWAYS:
|
||||
- Create stacks with `--anchor` from the start
|
||||
- Merge stacks bottom-to-top (base first, dependents after)
|
||||
- Snapshot before reorganizing: `but oplog snapshot --message "Before stack reorganization"`
|
||||
- Keep each level small (100-250 LOC) for reviewability
|
||||
- Delete empty branches after reorganization
|
||||
|
||||
NEVER:
|
||||
- Skip stack levels when merging
|
||||
- Stack independent, unrelated features (use virtual branches)
|
||||
- Create deep stacks (5+ levels) without good reason
|
||||
- Forget anchor when creating dependent branches
|
||||
|
||||
</rules>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause | Solution |
|
||||
|---------|-------|----------|
|
||||
| Stack not showing in `but status` | Missing `--anchor` | Recreate with correct anchor |
|
||||
| Commits in wrong stack level | Wrong branch targeted | `but rub <sha> correct-branch` |
|
||||
| Can't merge middle of stack | Wrong order | Merge bottom-to-top only |
|
||||
|
||||
## Recovery
|
||||
|
||||
To fix a branch with wrong/missing anchor: create new branch with correct anchor, move commits with `but rub`, delete original.
|
||||
|
||||
See `references/reorganization.md` for complete recovery procedures.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Planning
|
||||
|
||||
- Start simple: 2-3 levels max initially
|
||||
- Single responsibility per level
|
||||
- Only stack when there's a real dependency
|
||||
|
||||
### Maintenance
|
||||
|
||||
- Run `but status` regularly to verify structure
|
||||
- Commit to correct branches immediately
|
||||
- Clean up empty branches
|
||||
|
||||
### Communication
|
||||
|
||||
- Clear commit messages explaining why stack level exists
|
||||
- Descriptive names indicating stack relationship
|
||||
- Share `but status` when coordinating
|
||||
|
||||
<references>
|
||||
|
||||
### Reference Files
|
||||
|
||||
- **`references/patterns.md`** — Detailed stack patterns (feature dependency, refactoring, deep stacks)
|
||||
- **`references/reorganization.md`** — Post-hoc organization, squashing, moving commits, splitting
|
||||
|
||||
### Related Skills
|
||||
|
||||
- [gitbutler-virtual-branches](../virtual-branches/SKILL.md) — Core GitButler workflows
|
||||
- [gitbutler-complete-branch](../complete-branch/SKILL.md) — Merging to main
|
||||
- [gitbutler-multi-agent](../multi-agent/SKILL.md) — Multi-agent coordination
|
||||
|
||||
### External
|
||||
|
||||
- [GitButler Stacks Docs](https://docs.gitbutler.com/features/branch-management/stacked-branches)
|
||||
- [Stacked Branches Blog](https://blog.gitbutler.com/stacked-branches-with-gitbutler)
|
||||
|
||||
</references>
|
||||
@@ -0,0 +1,53 @@
|
||||
# Stack Patterns
|
||||
|
||||
Detailed patterns for GitButler stacked branches.
|
||||
|
||||
## Feature Dependency Stack
|
||||
|
||||
Build features that depend on each other in sequence.
|
||||
|
||||
```bash
|
||||
# Auth foundation
|
||||
but branch new auth-core
|
||||
but commit auth-core -m "feat: add authentication core"
|
||||
|
||||
# OAuth layer depends on auth core
|
||||
but branch new auth-oauth --anchor auth-core
|
||||
but commit auth-oauth -m "feat: add OAuth integration"
|
||||
|
||||
# Social login depends on OAuth
|
||||
but branch new auth-social --anchor auth-oauth
|
||||
but commit auth-social -m "feat: add social login"
|
||||
```
|
||||
|
||||
## Refactoring Stack
|
||||
|
||||
Break large refactors into reviewable phases.
|
||||
|
||||
```bash
|
||||
# Extract utilities
|
||||
but branch new refactor-extract-utils
|
||||
but commit refactor-extract-utils -m "refactor: extract common utilities"
|
||||
|
||||
# Update consumers
|
||||
but branch new refactor-use-utils --anchor refactor-extract-utils
|
||||
but commit refactor-use-utils -m "refactor: use extracted utilities"
|
||||
|
||||
# Clean up
|
||||
but branch new refactor-cleanup --anchor refactor-use-utils
|
||||
but commit refactor-cleanup -m "refactor: remove deprecated code"
|
||||
```
|
||||
|
||||
## Deep Stack (5+ Levels)
|
||||
|
||||
For complex features requiring many dependent phases.
|
||||
|
||||
```bash
|
||||
but branch new db-schema
|
||||
but branch new data-access --anchor db-schema
|
||||
but branch new business-logic --anchor data-access
|
||||
but branch new api-endpoints --anchor business-logic
|
||||
but branch new frontend-integration --anchor api-endpoints
|
||||
```
|
||||
|
||||
**Caution:** Deep stacks increase merge complexity. Prefer 2-3 levels when possible.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Stack Reorganization
|
||||
|
||||
Advanced techniques for reorganizing GitButler stacks.
|
||||
|
||||
## Post-Hoc Stack Organization
|
||||
|
||||
**Problem:** Created branches independently, now want to stack them.
|
||||
|
||||
**Solution:** Recreate with correct anchors:
|
||||
|
||||
```bash
|
||||
# Current: three independent branches
|
||||
# feature-a, feature-b, feature-c
|
||||
|
||||
# Stack feature-b on feature-a
|
||||
but branch new feature-b-stacked --anchor feature-a
|
||||
commit_sha=$(but show feature-b --json | jq -r '.commits[0].id')
|
||||
but rub $commit_sha feature-b-stacked
|
||||
but branch delete feature-b --force
|
||||
|
||||
# Stack feature-c on feature-b-stacked
|
||||
but branch new feature-c-stacked --anchor feature-b-stacked
|
||||
commit_sha=$(but show feature-c --json | jq -r '.commits[0].id')
|
||||
but rub $commit_sha feature-c-stacked
|
||||
but branch delete feature-c --force
|
||||
```
|
||||
|
||||
## Squashing Within Stack
|
||||
|
||||
Combine commits within the same stack level.
|
||||
|
||||
```bash
|
||||
# Squash all commits in a branch
|
||||
but squash my-branch
|
||||
|
||||
# Or squash specific commits
|
||||
but squash <newer-commit> <older-commit>
|
||||
```
|
||||
|
||||
## Moving Commits Between Stack Levels
|
||||
|
||||
Relocate a commit to the correct branch in the stack.
|
||||
|
||||
```bash
|
||||
# Use commit ID from `but status` or `but show`
|
||||
but rub <commit-id> correct-branch
|
||||
```
|
||||
|
||||
## Splitting a Branch
|
||||
|
||||
Extract part of a branch into a new stack level.
|
||||
|
||||
```bash
|
||||
# Original has multiple features
|
||||
but branch new second-feature --anchor original-branch
|
||||
# Use commit ID from `but show original-branch`
|
||||
but rub <commit-id> second-feature
|
||||
```
|
||||
|
||||
## Recovery
|
||||
|
||||
Recreate a branch with correct anchor when the original was created wrong.
|
||||
|
||||
```bash
|
||||
# Recreate branch with correct anchor
|
||||
but branch new child-stacked --anchor parent
|
||||
commit_sha=$(but show child --json | jq -r '.commits[0].id')
|
||||
but rub $commit_sha child-stacked
|
||||
but branch delete child --force
|
||||
```
|
||||
Reference in New Issue
Block a user