|
| 1 | +--- |
| 2 | +title: Development process using Branch-Out experience |
| 3 | +description: Learn how to developer can leverage Fabric branch-out experience into their development process |
| 4 | +ms.reviewer: PrigalYaron |
| 5 | +ms.topic: concept-article |
| 6 | +ms.date: 03/21/2026 |
| 7 | +--- |
| 8 | + |
| 9 | +# Development process using branched workspace |
| 10 | +*Branched workspace* is a workspace that is linked to a source workspace. It lets developers work on changes in an isolated environment, understand how their work relates to other workspaces, and promote changes back to the main workspace with confidence. |
| 11 | + |
| 12 | +The relationship (link) between a *Branched workspace* and its source workspace is established when the user performs branch-out. For Fabric developers, branch-out creates a new Git branch from the latest commit of the source workspace’s currently connected branch. The user can then either create a new workspace connected to that new branch, or use an existing workspace by switching its Git connection to the newly created branch. |
| 13 | + |
| 14 | +## Branched Workspace |
| 15 | +The *Branched workspace* relationship has several visual representations in the Fabric UI: |
| 16 | +- Workspace tree: Represents the source workspace as the parent of the branched workspace |
| 17 | + |
| 18 | + :::image type="content" source="media/branch-out/branch-6.png" alt-text="Workspace tree hierarchy with branched workspaces." lightbox="media/branch-out/branch-6.png"::: |
| 19 | + |
| 20 | +- Workspace breadcrumbs: Navigation option from branched workspace to source workspace |
| 21 | + |
| 22 | + :::image type="content" source="media/branch-out/branch-7.png" alt-text="Branched workspace breadcrumbs." lightbox="media/branch-out/branch-7.png"::: |
| 23 | + |
| 24 | +- Source control - [related branches](./git-integration-process.md#branches) tab |
| 25 | + |
| 26 | + :::image type="content" source="media/branch-out/branch-8.png" alt-text="Branched workspace related branches." lightbox="media/branch-out/branch-8.png"::: |
| 27 | + |
| 28 | +## Branch-Out Operation |
| 29 | + |
| 30 | +By default, when a branch‑out operation completes, all items from the source branch are included in the target workspace. This behavior can be changed by selecting **Select items individually (Preview)** during the branch‑out setup, allowing only chosen items to be included in the target workspace to allow faster time to code experience. |
| 31 | + |
| 32 | +As a Fabric developer, the branch-out flow would be as follows: |
| 33 | + |
| 34 | +1. From the *Branches* tab of the **Source control** menu, select **Branch out to another workspace**. |
| 35 | + |
| 36 | + :::image type="content" source="./media/manage-branches/branch-out.png" alt-text="Screenshot of source control branch out option."::: |
| 37 | + |
| 38 | +2. Specify if you want to create a new workspace or branch-out into an existing one. Specify the names of the new branch and workspace, or select the existing workspace from the dropdown list. Check the **Select items individually (Preview)** in case you would like to work only on subset of the items in the branched workspace. You will see the following screenshot when creating a new workspace with selective branching. |
| 39 | + |
| 40 | + >[!NOTE] |
| 41 | + >When you branch out to a workspace, any items that aren't saved to Git can get lost. We recommend that you commit any items you want to keep before branching out. |
| 42 | + |
| 43 | + :::image type="content" source="media/branch-out/branch-2.png" alt-text="Screenshot of select items individually." lightbox="media/branch-out/branch-2.png"::: |
| 44 | + |
| 45 | + >[!IMPORTANT] |
| 46 | + >When branching out to an existing workspace, some items may be deleted. You must confirm that you understand this risk before proceeding with the operation |
| 47 | +
|
| 48 | +3. Click the **Branch out** button (steps 4-8 apply only when **Select items individually (Preview)** is selected) |
| 49 | +4. This action brings up a dialog to **Select items for your workspace**. |
| 50 | + |
| 51 | + >[!NOTE] |
| 52 | + >If the Git branch contains a large number of items, the Select items dialog may take some time to load. |
| 53 | +
|
| 54 | +5. Select the items that you want for this workspace. |
| 55 | +6. Click **Create branch**. |
| 56 | + :::image type="content" source="media/branch-out/branch-4.png" alt-text="Screenshot of create branch." lightbox="media/branch-out/branch-4.png"::: |
| 57 | +7. When you perform selective branching, all the item’s dependencies are required. You can use the **select related items** button for that purpose. If you don't select one of the dependencies, you see the following: |
| 58 | + :::image type="content" source="media/branch-out/branch-3.png" alt-text="Screenshot of dependency error." lightbox="media/branch-out/branch-3.png"::: |
| 59 | +8. Once the branch is created, you can verify that you are in a selective branch by the icon in the bottom status bar (lower left corner). It says selective branch. |
| 60 | +:::image type="content" source="media/branch-out/branch-5.png" alt-text="Screenshot of selective branch icon." lightbox="media/branch-out/branch-5.png"::: |
| 61 | +9. Fabric creates the new branched workspace. You're automatically taken to the new workspace. It contains all items or only the items that you selected in case of selective branching. |
| 62 | + |
| 63 | + The workspace syncs with your feature branch, and becomes an isolated environment to work in, as illustrated. You can now work in this new branched workspace. The sync might take a few minutes. For more information on branching out, see [troubleshooting tips](../troubleshoot-cicd.md#branching-out-i-dont-see-the-branch-i-want-to-connect-to). |
| 64 | + |
| 65 | + :::image type="content" source="./media/manage-branches/branches-update-commit.png" alt-text="Diagram showing the workflow of commits."::: |
| 66 | + |
| 67 | +10. Save your changes and [commit](./git-get-started.md#commit-changes-to-git) them into the feature branch. |
| 68 | +11. When ready, create a PR to the *main* branch. The review and merge processes are done through related Git provider based on the configuration your team defined for that repo. |
| 69 | + |
| 70 | +Once the review and merge are complete, a new commit is created to the *main* branch. This commit prompts the user to update the content in the Dev team's workspace with the merged changes. |
| 71 | + |
| 72 | +For more information, see [branching out limitations](#branching-out-limitations). |
| 73 | + |
| 74 | +### How to add additional items to a workspace with selective branching |
| 75 | +When a Fabric developer needs to add items that were not selected during the branch‑out operation, the steps below describe how to add additional items to the workspace: |
| 76 | +1. Go to the required Fabric workspace, and select **Source control** at the top. |
| 77 | +2. On the right, select the **branch out** symbol. |
| 78 | +3. Use the drop-down and select **Select additional items**. |
| 79 | +4. This action brings up a dialog to **Select items for your workspace**. The select items dialog shows **only** items from the git branch that weren't previously selected. |
| 80 | +5. Select the additional items you want to add to the workspace. |
| 81 | +6. Click **Add**. The selected items are added to the pending updates in the source control pane. |
| 82 | +7. Click **Update all**. This operation performs an update from git and creates the items in the workspace. |
| 83 | + |
| 84 | +### Switch branches |
| 85 | +If your workspace is connected to a Git branch and you want to switch to another branch, you can do so quickly from the **Source control** pane without disconnecting and reconnecting. |
| 86 | + |
| 87 | +When you switch branches, the workspace syncs with the new branch and all items in the workspace are overridden. If there are different versions of the same item in each branch, the item is replaced. |
| 88 | + |
| 89 | +Perfroming switch branch doesn't affect the relationship (link) between a *branched workspace* and its source workspace. Branch switching is a Git state change. Thus, switching branches doesn't create or modify workspace relationships. If a workspace already has a relationship, then it is preserved. |
| 90 | + |
| 91 | +>[!NOTE] |
| 92 | +>When switching branches, if the workspace contains an item in the old branch but not the new one, the item is deleted. Additionally, in a workspace with selective branching, performing a switch operation resets the item selection, and all items from the switched branch are synchronized to the workspace. |
| 93 | +
|
| 94 | +To switch between branches, follow these steps: |
| 95 | + |
| 96 | +1. From the *Branches* tab of the **Source control** menu, select **Switch branch**. |
| 97 | + |
| 98 | + :::image type="content" source="media/manage-branches/check-out-new-branch.png" alt-text="Screenshot of source control check out a new branch option."::: |
| 99 | + |
| 100 | +1. Specify the branch you want to connect to or create a new branch. This branch must contain the same directory as the current branch. |
| 101 | + |
| 102 | +1. Place a check in **I understand workspace items may be deleted and can't be restored.** and select **Switch branch**. |
| 103 | + |
| 104 | + :::image type="content" source="media/manage-branches/switch-branch-component.png" alt-text="Screenshot of switching branches."::: |
| 105 | + |
| 106 | +You can't switch branches if you have any uncommitted changes in the workspace. Select **Cancel** to go back and commit your changes before switching branches. |
| 107 | + |
| 108 | +To connect the current workspace to a new branch while keeping the existing workspace status, select **Checkout new branch**. Learn more about checking out a new branch at [Resolve conflicts in Git](./conflict-resolution.md#resolve-conflict-in-git). |
| 109 | + |
| 110 | +### Branching out limitations |
| 111 | + |
| 112 | +- Branch out requires permissions listed in [permissions table](./git-integration-process.md#permissions). |
| 113 | +- There must be an available capacity for this action. |
| 114 | +- All [workspace](./git-integration-process.md#workspace-limitations) and [branch naming limitations](./git-integration-process.md#branch-and-folder-limitations) apply when branching out to a new workspace. |
| 115 | +- Only [Git supported items](./intro-to-git-integration.md#supported-items) are available in the new workspace. |
| 116 | +- The related branches list only shows branches and workspaces you have permission to view. |
| 117 | +- [Git integration](../../admin/git-integration-admin-settings.md) must be enabled. |
| 118 | +- When branching out, a new branch is created and the settings from the original branch aren't copied. Adjust any settings or definitions to ensure that the new meets your organization's policies. |
| 119 | +- When disconnecting a *branched workspace* from Git, its relationship to the source workspace is removed as well. |
| 120 | +- When disconnecting a Git-connected workspace that has related *branched workspaces*, all branched workspace relationships are removed as well. |
| 121 | +- When deleting a workspace that has related *branched workspaces*, all branched workspace relationships are removed, and the branched workspaces become regular workspaces. |
| 122 | +- When branching out to an existing workspace: |
| 123 | + - The target workspace must support a Git connection. |
| 124 | + - The user must be an admin of the target workspace. |
| 125 | + - The target workspace must have capacity. |
| 126 | + - The workspace can't have template apps. |
| 127 | + - The target workspace can’t have any related *branched workspaces*. |
| 128 | + |
| 129 | +- **Note that when you branch out to a workspace, any items that aren't saved to Git can get lost. We recommend that you [commit](./git-integration-process.md#commits-and-updates) any items you want to keep before branching out.** |
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments