Skip to content

Commit

Permalink
fix: update llm output file name
Browse files Browse the repository at this point in the history
  • Loading branch information
@ndom91
ndom91 committed Jan 7, 2025
1 parent 976163a commit 3a529af
Show file tree
Hide file tree
Showing 2 changed files with 168 additions and 168 deletions.
334 changes: 167 additions & 167 deletions public/llms.txt → public/llms-full.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -347,173 +347,6 @@ If none of the available options helps, feel free to hop on our [Discord](https:



# stacked-branches.mdx


Create a stack of dependent branches to be reviewed and merged in order.

## Overview

GitButler allows you to create an ordered stack of branches where each branch depends on (and is based on) the previous one.
The application also supports creating the appropriate stacked Pull Requests (when used with a GitHub remote).
This is useful when you have multiple changesets that depend on each other but it is desirable to have them reviewed and merged separately (and in sequence).

> 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="/stacked-branches/0_concepts.jpg" />

## Use cases

Using stacked branches (Pull Requests) can be helpful for shipping smaller changes more frequently.

### Breaking up a larger change into smaller ones

Consider a scenario where you are implementing a medium/large feature in your software project.
In the course of implementation you end up performing the following sub-tasks:

1. Refactor a part of the codebase to accommodate the new feature
2. Implement an API endpoint supporting the feature
3. Implement the frontend part of the feature consuming the API

While the feature is considered complete only when all of the subtasks are implemented, reviewed and merged, in many cases it is considered beneficial
to ship each stage of the feature on its own, potentially behind a feature flag. Not only the risk of merge conflicts with colleagues is reduced,
but also eventual bugs are easier to track down / revert / fix as compared to a single large change.

### More granular (easier) review process

On GitHub at least, code reviews are performed on per-branch basis. While it is possible to view individual commits in a Pull Request, it is not possible to
approve and merge a subset of commits from the PR.

Utilizing stacked pull requests, means that the sub-tasks of a larger change are in their own PRs.
This way it is possible to approve and merge the initial part of a stack (e.g. a refactor) while still iterating on the remaining sub-tasks.

## Comparison to Virtual Branches

Stacking and Virtual Branches are similar in that they allow you to separate code changes / commits into different branches. In both cases,
the changes are available in your working directory.

The main difference is that Virtual Branches are **independent** from one another, while stacked branches **depend** on the ones that come before it.
Because of this, the two features are not mutually exclusive but rather complementary. For example a bugfix change that is unrelated to a feature
can be put in a separate virtual branch. On the other hand, a change that depends on a previous change can be put in a stacked branch above the one it depends on.

In fact GitButler implements stacked branches as Virtual Branches that are split into multiple dependent branches.

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

## Workflow

By default, virtual branches in the app are simply stacks of one. With version `0.14.0` or newer
you can create a new dependent branch within a lane by clicking the `+` button above the branch name.

> The workflow below assumes a GitHub remote. If you are using a different forge, you can still use this functionality but will need to manually create/update the Pull/Merge Requests

1. Creating a new dependent branch forms a stack within the lane.

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

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

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

3. Pushing is done for the stack as a whole. Note: The Pull Requests will be created in a way where each branch points to its parent - see [Automatic branch deletion](#automatic-branch-deletion)

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

4. Pull requests must be created one at a time starting from the bottom of the stack.

<ImageSection src="/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="/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.

<ImageSection
src="/stacked-branches/6_modify_commits-amend.jpg"
subtitle="Amending a commit"
/>
<ImageSection
src="/stacked-branches/6_modify_commits-move.jpg"
subtitle="Moving a commit to a different branch"
/>
<ImageSection
src="/stacked-branches/6_modify_commits-squash.jpg"
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.

<ImageSection src="/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="/stacked-branches/8_merging-1.jpg" />
<ImageSection src="/stacked-branches/8_merging-2.jpg" />

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

## GitHub configuration for stacked PRs

_TLDR:_

1. Enable automatic branch deletion [automatic branch deletion](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches)
on GitHub.
2. If possible, consider using the the "Merge" strategy when merging PRs.

#### Automatic branch deletion

When reviewing a PR in a stack, it is important to be able to view only the changes in the branch that is being reviewed.
Of course, in pure Git terms, a stacked branch will contain all the changes from the branches below it.

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 branch in the stack, which targets the default branch of the repository as usual.

<ImageSection src="/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 its parent.
When the bottom 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="/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.

_NB:_ If you merge the first PR but the branch is not deleted and then merge the second PR,
the app can still recover from this, see [Troubleshooting](#troubleshooting).

#### Merge strategy

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.
The reason for this is with merge commits you will be able to merge all the branches in the stack from GitHub without having to force push in the app.

## Troubleshooting

Firstly, if you run into any issue with the app (stacking or not), you can always get in touch either
on [Discord](https://discord.com/invite/MmFkmaJ42D) or via the in-app feedback icon (we will get back via email).
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 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.

#### Accidentally merged a branch into a branch before it (not integrated into main/master yet)

Merging of branches in a stack should be done from the bottom up. With the GitHub interface, it is possible to incorrectly merge a Pull Request which is in the middle of the stack.
In this case it will merged in the parent branch.

In order to recover from this situation you can simply force push the branches and then re-create the PR that was incorrectly merged.


# recovering-stuff.mdx


Expand Down Expand Up @@ -756,6 +589,173 @@ The virtual_branches tree has the actual contents of those computed branches in
This allows you to get contents of any file in any of your virtual branch states as well.


# stacked-branches.mdx


Create a stack of dependent branches to be reviewed and merged in order.

## Overview

GitButler allows you to create an ordered stack of branches where each branch depends on (and is based on) the previous one.
The application also supports creating the appropriate stacked Pull Requests (when used with a GitHub remote).
This is useful when you have multiple changesets that depend on each other but it is desirable to have them reviewed and merged separately (and in sequence).

> 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="/stacked-branches/0_concepts.jpg" />

## Use cases

Using stacked branches (Pull Requests) can be helpful for shipping smaller changes more frequently.

### Breaking up a larger change into smaller ones

Consider a scenario where you are implementing a medium/large feature in your software project.
In the course of implementation you end up performing the following sub-tasks:

1. Refactor a part of the codebase to accommodate the new feature
2. Implement an API endpoint supporting the feature
3. Implement the frontend part of the feature consuming the API

While the feature is considered complete only when all of the subtasks are implemented, reviewed and merged, in many cases it is considered beneficial
to ship each stage of the feature on its own, potentially behind a feature flag. Not only the risk of merge conflicts with colleagues is reduced,
but also eventual bugs are easier to track down / revert / fix as compared to a single large change.

### More granular (easier) review process

On GitHub at least, code reviews are performed on per-branch basis. While it is possible to view individual commits in a Pull Request, it is not possible to
approve and merge a subset of commits from the PR.

Utilizing stacked pull requests, means that the sub-tasks of a larger change are in their own PRs.
This way it is possible to approve and merge the initial part of a stack (e.g. a refactor) while still iterating on the remaining sub-tasks.

## Comparison to Virtual Branches

Stacking and Virtual Branches are similar in that they allow you to separate code changes / commits into different branches. In both cases,
the changes are available in your working directory.

The main difference is that Virtual Branches are **independent** from one another, while stacked branches **depend** on the ones that come before it.
Because of this, the two features are not mutually exclusive but rather complementary. For example a bugfix change that is unrelated to a feature
can be put in a separate virtual branch. On the other hand, a change that depends on a previous change can be put in a stacked branch above the one it depends on.

In fact GitButler implements stacked branches as Virtual Branches that are split into multiple dependent branches.

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

## Workflow

By default, virtual branches in the app are simply stacks of one. With version `0.14.0` or newer
you can create a new dependent branch within a lane by clicking the `+` button above the branch name.

> The workflow below assumes a GitHub remote. If you are using a different forge, you can still use this functionality but will need to manually create/update the Pull/Merge Requests

1. Creating a new dependent branch forms a stack within the lane.

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

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

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

3. Pushing is done for the stack as a whole. Note: The Pull Requests will be created in a way where each branch points to its parent - see [Automatic branch deletion](#automatic-branch-deletion)

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

4. Pull requests must be created one at a time starting from the bottom of the stack.

<ImageSection src="/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="/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.

<ImageSection
src="/stacked-branches/6_modify_commits-amend.jpg"
subtitle="Amending a commit"
/>
<ImageSection
src="/stacked-branches/6_modify_commits-move.jpg"
subtitle="Moving a commit to a different branch"
/>
<ImageSection
src="/stacked-branches/6_modify_commits-squash.jpg"
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.

<ImageSection src="/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="/stacked-branches/8_merging-1.jpg" />
<ImageSection src="/stacked-branches/8_merging-2.jpg" />

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

## GitHub configuration for stacked PRs

_TLDR:_

1. Enable automatic branch deletion [automatic branch deletion](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches)
on GitHub.
2. If possible, consider using the the "Merge" strategy when merging PRs.

#### Automatic branch deletion

When reviewing a PR in a stack, it is important to be able to view only the changes in the branch that is being reviewed.
Of course, in pure Git terms, a stacked branch will contain all the changes from the branches below it.

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 branch in the stack, which targets the default branch of the repository as usual.

<ImageSection src="/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 its parent.
When the bottom 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="/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.

_NB:_ If you merge the first PR but the branch is not deleted and then merge the second PR,
the app can still recover from this, see [Troubleshooting](#troubleshooting).

#### Merge strategy

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.
The reason for this is with merge commits you will be able to merge all the branches in the stack from GitHub without having to force push in the app.

## Troubleshooting

Firstly, if you run into any issue with the app (stacking or not), you can always get in touch either
on [Discord](https://discord.com/invite/MmFkmaJ42D) or via the in-app feedback icon (we will get back via email).
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 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.

#### Accidentally merged a branch into a branch before it (not integrated into main/master yet)

Merging of branches in a stack should be done from the bottom up. With the GitHub interface, it is possible to incorrectly merge a Pull Request which is in the middle of the stack.
In this case it will merged in the parent branch.

In order to recover from this situation you can simply force push the branches and then re-create the PR that was incorrectly merged.


# timeline.mdx


Expand Down
2 changes: 1 addition & 1 deletion scripts/generate-llmstxt.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,4 @@ await Promise.all(
})
)

await writeFile("./public/llms.txt", fileContent)
await writeFile("./public/llms-full.txt", fileContent)

0 comments on commit 3a529af

Please sign in to comment.