diff --git a/content/docs/features/stacked-branches.mdx b/content/docs/features/stacked-branches.mdx index edbf4a3..b49ae9f 100644 --- a/content/docs/features/stacked-branches.mdx +++ b/content/docs/features/stacked-branches.mdx @@ -14,10 +14,7 @@ This is useful when you have multiple changesets that depend on each other but i > All of the Pull Request stack orchestration is done locally in the client, which means that your repo content is not shared with a cloud service. - + ## Use cases @@ -55,9 +52,7 @@ can be put in a separate virtual branch. On the other hand a change that depends In fact GitButler implements stacked branches as Virtual Branches that are split into multiple dependent branches which makes for a flexible workflow. - + ## Workflow @@ -68,33 +63,23 @@ you can create a new dependent branch within a lance with the `+` button above t 1. Creating a new dependent branch forms a new stack within the virtual branch - + 2. New commits land in the topmost branch of the stack - + 3. Pushing is done for the stack as a whole - + 4. Pull request creation has to be done from the bottom of the stack upwards - + 5. The PRs will contain a footer with stack information and as you add more PRs it will keep all up to date - + 6. You can drag changes into commits to amend them (e.g. incorporating review feedback) as well as move and squash commits @@ -111,22 +96,16 @@ you can create a new dependent branch within a lance with the `+` button above t subtitle="Squashing commits" /> +7. If a change in your stack is independent (e.g. an unrelated bugfix) it can be moved to a different virtual branch (or stack). + This works for both uncommitted changes and existing commits that you may want to relocate. -7. If a change in your stack is independent (e.g. an unrelated bugfix) it can be moved to a different virtual branch (or stack1) - - + 8. Review/merge your PRs starting from the bottom up. After a PR/branch from your stack has been merged, it is reflected in the Stack and you should force push to reflect the changes on the remote as well - - + + 9. When all branches of a stack have been merged, the stack is complete @@ -146,10 +125,7 @@ Of course, in pure Git terms, a stacked branch will contain all the changes from In order to show only the expected Files changed and Commits for PRs in a stack, each PR is created to target the branch below it in the stack. This is true for all but the bottom-most branch in the stack, which targets the default branch of the repository as usual. - + > Every branch in the stack contains the commits from the branches below it. @@ -157,9 +133,7 @@ This of course does not mean that a Pull Request should be merged into it's pred When the bottom-most branch is merged on GitHub, **if** the PR branch is deleted, GitHub will automatically update any PRs that used to target it to target the default branch instead. - + If the newly merged branch from the bottom of the stack is not deleted, the next PR in line will still target it and there is a risk of accidentally merging it into the now out of data branch. For this reason it is _highly recommended_ to [enable on GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches) the automatic deletion of branches after merging. @@ -172,8 +146,6 @@ the app can still recover from this, see [Troubleshooting](#troubleshooting). The app will support any merge strategy you wish to use - "Merge", "Rebase" or "Squash". However, due to the nature of merge, the GitButler will be able to create a slightly better experience if the "Merge" strategy is used. -[//]: # "TODO: Screenshot of both" - ## Troubleshooting Firstly, if you run into any issue with the app (stacking or not), you can always reach get in touch either @@ -182,8 +154,8 @@ With that said, here are some workarounds for common issues. #### Accidentally merged a stack branch into an already merged branch before it -If you merged the bottom Pull Request into main but the branch was _not_ deleted, then the targed of the next Pull Request would not be automatically updated. -Under these contitions merging that next Pull Request, means it would be merged into the original, now out of date, bottom PR. +If you merged the bottom Pull Request into main but the branch was _not_ deleted, then the target of the next Pull Request would not be automatically updated. +Under these conditions merging that next Pull Request, means it would be merged into the original, now out of date, bottom PR. A mitigation for this is to rename the branch, push and re-create the Pull Request.