Skip to content

Commit

Permalink
Fixed a few typos in docs
Browse files Browse the repository at this point in the history
  • Loading branch information
krlvi committed Nov 26, 2024
1 parent d9d19d7 commit e47cda6
Showing 1 changed file with 16 additions and 44 deletions.
60 changes: 16 additions & 44 deletions content/docs/features/stacked-branches.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
<ImageSection
className="mx-auto"
src="/img/docs/stacked-branches/0_concepts.jpg"
/>
<ImageSection className="mx-auto" src="/img/docs/stacked-branches/0_concepts.jpg" />

## Use cases

Expand Down Expand Up @@ -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.

<ImageSection
src="/img/docs/stacked-branches/11_overview.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/11_overview.jpg" />

## Workflow

Expand All @@ -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

<ImageSection
src="/img/docs/stacked-branches/1_creating_stack.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/1_creating_stack.jpg" />

2. New commits land in the topmost branch of the stack

<ImageSection
src="/img/docs/stacked-branches/2_new_commits.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/2_new_commits.jpg" />

3. Pushing is done for the stack as a whole

<ImageSection
src="/img/docs/stacked-branches/3_push_all.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/3_push_all.jpg" />

4. Pull request creation has to be done from the bottom of the stack upwards

<ImageSection
src="/img/docs/stacked-branches/4_create_pr.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/4_create_pr.jpg" />

5. The PRs will contain a footer with stack information and as you add more PRs it will keep all up to date

<ImageSection
src="/img/docs/stacked-branches/5_pr_footer.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/5_pr_footer.jpg" />

6. You can drag changes into commits to amend them (e.g. incorporating review feedback) as well as move and squash commits

Expand All @@ -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)

<ImageSection
src="/img/docs/stacked-branches/7_move_to_vb.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/7_move_to_vb.jpg" />

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

<ImageSection
src="/img/docs/stacked-branches/8_merging-1.jpg"
/>
<ImageSection
src="/img/docs/stacked-branches/8_merging-2.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/8_merging-1.jpg" />
<ImageSection src="/img/docs/stacked-branches/8_merging-2.jpg" />

9. When all branches of a stack have been merged, the stack is complete

Expand All @@ -146,20 +125,15 @@ 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.

<ImageSection

src="/img/docs/stacked-branches/9_pr_heads.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/9_pr_heads.jpg" />

> Every branch in the stack contains the commits from the branches below it.
This of course does not mean that a Pull Request should be merged into it's predecessor.
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.

<ImageSection
src="/img/docs/stacked-branches/10_branch_deletion.jpg"
/>
<ImageSection src="/img/docs/stacked-branches/10_branch_deletion.jpg" />

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.
Expand All @@ -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
Expand All @@ -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.

Expand Down

0 comments on commit e47cda6

Please sign in to comment.