Guide to branching

Related Videos

• Share a branch

  Who can share branches

  Only people with an editor role in an organization or workspace can access the branching feature.

  Anyone with access to the main file can share branches.

  This article covers one step in the branching process:

  Create → Share → Update → Request → Review → Merge → Manage

  If you're working on revisions or iterations on a branch, you may want to share your progress with other designers and collaborators.

  Everyone with access to the main file can view and explore branches of that file. You can also share branches with other collaborators to allow them to view or edit their contents.

  Giving someone can view or can edit access to a branch also gives them view access to the main file.

  There are a few ways to share branches.

  • A

    Main file

    Anyone with can view access to the main file can view any branches on that file.

    1. Click the next to the file/branch name in the toolbar.
    2. Select See all branches to open the branches modal.
    3. Select the branch to open it in the Editor.
       Tip! You can tell if a file link is for a main file or a branch as all branches will include a /branch/ variable and a unique string for that branch.
  • B

    Share link

    Share a branch link and control access to the branch using link sharing.

    1. Open the branch.
    2. Click the Share button in the toolbar.
    3. Click the link sharing setting.
    4. Select Anyone with a link to allow anyone to access the file using the file link.
    5. Click Copy link to add the branch link to your clipboard.

    Caution: The Allow viewers to copy, share, or export from the file setting must be enabled for viewers to create branches. If this is disabled, viewers won't see the option to create or edit branches.

  • C

    Invite to branch

    Invite a collaborator to the branch with specific permissions.

    1. Click the Share button in the top-right corner.
    2. Enter the collaborator's email in the email field.
    3. Click to adjust their permissions.
       • Select can view to give them view-only access to files in that project.
       • Select can edit to give them edit access to any files in that project.
    4. Click Send invite to send an email invitation to their address. If they're already using Figma, they'll get an in-app notification as well.

  Tip! You can also copy a link to a branch from the branches modal. View and manage branches →

• Get updates from main files

  Who can get updates

  Only people with an editor role in an organization or workspace can access the branching feature.

  Anyone with can edit access to a branch can receive and apply updates from the main file.

  This article covers one step in the branching process:

  Create → Share → Update → Request → Review → Merge → Manage

  If changes are made in the main file, Figma will notify any branches that updates are available. If you have edit access to the branch, you can review and apply those updates to your branch.

  It's not possible to choose which changes from the main file you want to apply. You'll need to receive all updates from the main file.

  If there are changes to layers you are editing in your branch, you may need to resolve conflicts. You can do this as soon as new changes are available, or when you merge the branch.

  Caution: If you have an active memory limit banner in your file, you can't review and merge changes. Figma will disable the Review and merge changes setting. To get updates from the main file or merge a branch, you need to reduce your memory usage.

  Review and apply changes

  When you accept updates, Figma applies any changes to existing layers, components, or styles in your branch. If new assets were created in the main file, Figma will also add these to your branch. If you've created new assets in your branch, these changes won't have any affect on those assets.

  1. Expand the menu next to the file/branch name in the toolbar.
  2. Select Update from main... to preview any updates.
  3. View a list of items that have been , , or . You can see a preview of the latest versions, but it's not a before and after of what's changed.
  4. Select Apply changes to apply all updates to your branch.

  Resolve conflicts

  If other collaborators have been continuing to make changes to the main file, you may have conflicting changes. This means one or more of the elements you've made changes to has been updated in the main file.

  Figma will let you know if there are any conflicting changes from the Update from main file modal.

  1. Click Resolve conflicts to view any conflicts.
  2. View a list of conflicts in the left sidebar.
  3. Select an option from the list to review the conflicting changes side-by-side. The version from the main file (source) is on the left and the branch on the right.
  4. Select which version you would like to use. Figma will add a badge next to the conflict to show whether you selected the main or branch.
  5. Repeat the process for the remaining conflicts. You'll need to choose a version for every conflict.
  6. To quickly select the same option for every conflict, use the Resolve all menu. Choose from:
     • Pick main file to use the latest changes from the main file
     • Pick branch to keep the changes in your branch.
  7. When you have a selection for every conflict, click Next to move to the next step.
  8. You can now preview any other updates from the main file, if there are any. Click Apply changes to apply those updates.
  9. Figma will apply updates from the main file return you to the branch. You can then continue to edit your branch. If you're receiving updates as part of a branch merge, you can complete the rest of the process.

  Reverse or undo updates

  If you want to undo or reverse a branch update, you can restore a previous version of the branch. If you notice something doesn’t look right after a merge or update, read our Incomplete updates and merges article.

  1. From the branch, click the next to the file/branch name in the toolbar.
  2. Select Show version history to open version history in the right sidebar.
  3. Select a version before the update from the main file.
  4. Right-click the version or click the and select Restore this version.
  5. Figma will add two autosave checkpoints to the file's version history. A checkpoint that saves the current version. This is an autosaved version with a timestamp that matches the current time. A checkpoint at the same timestamp for the version you just restored.
  6. Click Done in the toolbar to exit version history.
• View and manage branches

  Who can view branches

  Only people with an editor role in an organization or workspace can access the branching feature.

  Anyone with can view or can edit access to the main file can view branches.

  This article covers one step in the branching process:

  Create → Share → Update → Request → Review → Merge → Manage

  View and manage branches of a Figma design file from the branches modal. You can identify design files with branches using the icon.

  View branches

  You can view a file's branches from the main file, or in the file browser.

  Main file

  1. Click the next to the file/branch name in the toolbar.
  2. Select See all branches to open the branches modal.
  3. If you have can edit access to the main file, you can take further action on branches from the file name menu:
     • Select Duplicate as new file to create a new file from the branch. This will create a separate file, so you won't be able to apply any changes from that file back to the main file.
     • Select Rename to change the name of the branch (from branch only)
     • Select Archive to archive the current branch without merging (from branch only)

  

  File browser

  If a file has branches, you'll see an icon on the top-left of the file tile, and the total number of branches underneath the file name.

  • Click to view the main file
  • Use the dropdown to select one of the branches

  

  Manage branches

  View all branches in the Branches modal. You'll see three tabs for Active and Archived branches, as well as branches you created (Yours). The Archived tab includes both merged and archived branches.

  If you have can edit access to the main file, you can do the following from the Branches modal:

  • Open a branch
  • Merge a branch
  • Archive a branch
  • Copy link to branch
  • Rename a branch
  • Restore an archived branch

  Open branch

  You can open, view, and explore any active or archived branches. You can view any pages, comments, and a full version history for that branch.

  1. Find the branch you want to open. You can find merged branches in the Archived tab.
  2. Hover over the branch and click Open. Figma will open that branch in the editor.

  Archive branch

  Archive any historic, abandoned, or incomplete branches.

  1. Find the branch you want to archive.
  2. Click to open the menu.
  3. Select Archive to move the branch to the Archived tab.

  Copy link to branch

  Copy a link to the branch to share the file URL with a co-worker or collaborator.

  1. Open the branches modal.
  2. Next to the branch you want to share, click to open the menu.
  3. Select Copy link to add the URL for the branch to your clipboard.

  

  Rename branch

  1. Open the branches modal.
  2. Next to the branch you want to share, click to open the menu.
  3. Select Rename from the options.
  4. The branch name will now be an editable field. Enter the new name in the field provided.
  5. Press Enter or click outside the field to apply your changes.

  Restore an archived branch

  Restore an archived branch. This allows you to continue to edit the file, as well as merge your updates into the main file. It's not possible to restore a merged branch. 

  1. Select the Archived tab.
  2. Find the archived branch.
  3. Click to open the menu.
  4. Select Restore to continue to edit the branch.
• Request a branch review

  Who can request a review

  Only people with an editor role in an organization or workspace can access the branching feature.

  Anyone with can view or can edit access to the main file can request a review.

  This article covers one step in the branching process:

  Create → Share → Update → Request → Review → Merge → Manage

  When you're finished making changes in your branch, you can request one or more people to review and approve the changes before merging the branch to the main file.

  If you don’t have edit access to the main file, you must request a merge from someone who does have edit access. Reviewers can either Approve the branch or Request changes.

  You can request a review from anyone who has access to the main file. This can include members of the team, as well as anyone who has access to the file or project.

  A reviewer can then review the changes in your branch and choose whether to approve them or suggest changes.

  Request review

  When you're finished making changes in your branch, you can request one or more people to review and approve the changes before merging the branch to the main file. This process is not a requirement for merging to the main file.

  1. Open the branch you want reviewed.
  2. Expand the menu next to the file/branch name in the toolbar.
  3. Click Request review to open the Branch review modal.
  4. You can then preview any changes you've made as well as select reviewers to approve the changes.
     • Figma will suggest people with edit access to the main file. editors on your team, click Add next to the suggestion to add them as a reviewer.
     • To select another team member, or someone outside of your team, click .
       • Browser Other team members in the list.
       • Use the Search field to find a specific person.
       
  5. Once you've added your reviewer(s), click Request review.
  6. Use the description field to give reviewers more context for the changes you're making. <IMAGE: Request review pop up from button>
  7. Click Send to reviewers to submit the request.

  Figma will notify reviewers by in-app notification and email. A label will also appear next to your branch name in the toolbar to show the branch is In review.

  View reviewer feedback

  Reviewers can choose to approve your branch or suggest further changes. Figma will send you a notification and email (if enabled) to let you know the review outcome.

  There are three possible outcomes from a review, Figma represents these outcomes as a status next to the branch name in the toolbar:

  • Approved: Your changes have been approved, but the branch has not been merged. This usually means the reviewer does not have edit access to the main file, or is waiting for other reviewers to add their review before merging.
  • Changes suggested: A yellow badge indicates that the reviewer needs you to make some changes before the branch is accepted. You can open the review modal to view the suggestions.
    Reviewers may have added feedback to individual layers or designs using comments. If there are comments, you'll see a banner with a View comments banner.
  • Merged: Your changes from the branch have been approved and merged into the main file. The branch will be archived and locked.

  

  Resend request

  Resend a review request to any reviewers. You can do this to remind a reviewer of an outstanding review or to submit another request after making changes.

  1. Open the branch you want reviewed.
  2. Expand the menu next to the file/branch name in the toolbar.
  3. Select Request review to open the Branch review modal.
  4. Select Resend review request.
  5. Update the description of the review to account for any changes (optional).
  6. Click Send to reviewer. Figma will notify any reviewers of the request via email and in-app notification.
• Review branch changes

  Who can review branches

  Only people with an editor role in an organization or workspace can access the branching feature.

  Anyone with can view or can edit access to the branch can review changes.

  Anyone with can edit access to the main file can merge branches.

  This article covers one step in the branching process:

  Create → Share → Update → Request → Review → Merge → Manage

  Branch creators can request a review from a team member or other collaborator before merging a branch. You'll receive an email and notification when someone adds you as a branch reviewer.

  Reviewers can view all the changes included in the branch. They can then choose to Approve a branch, or Suggest changes from the branch's creator.

  If you only have view access to the main file, you can still review a branch. If you have edit access to the main file, you can also merge an approved branch.

  Open branch

  • Click the notification or open the link from your email to access the branch's Branch review modal.
  • Open the branch you want to review, click the menu next to the file/branch name in the toolbar, and select Review and merge changes.

  Review changes

  Branch reviews apply to all changes in a branch. There isn't a way to approve some changes and reject others.

  You can use the review process to suggest changes to the branch creator. They can then make those changes and resubmit the branch for review.

  1. In the left sidebar of the Branch review window you can see a summary of the branch. This includes the branch name, the main file, and the total number of changes.
  2. View details of the review request in the Review request section. This includes a description of the branch added by the branch creator, and the date and time the review was requested.
  3. In the main body of the window you can view a list of components, instances, or layers that have been , , , or . Figma groups changes by page, click the page name to collapse or expand the changes in each page.
  4. Select an object or page to view changes for a specific layer or component.

  

  With a layer or component selected you can:

  1. View the layer, frame, or component name at the top of the modal. Click in the top left to go back to the review summary.
  2. View changes side by side or as an overlay.
  3. Use the buttons to:
     • Zoom in
     • Zoom out
     • Zoom to Fit
  4. View details of the changes, including any layers or specific properties changed.
  5. If there are multiple changes, use the and arrows at the bottom to view other changes.

  

  Approve branch

  If you're happy with all of the changes you can approve the branch. If you have edit access to the main file you can also merge the branch into the main file.

  To add your approval:

  1. Click Add your review in the bottom-right corner of the window.
  2. In the Finish your review dialog, select Approve.
  3. Add any comments you want to make (optional).
  4. Select Submit to approve the branch. You'll see an Approved badge next to the branch name in the toolbar.

  

  Suggest changes

  If there are changes you'd like the branch creator to make before merging, you can suggest changes. You can add a summary of the changes during the review process.

  If there are specific changes or suggestions you'd like to make, you can also add comments to the individual designs. Comments are specific to the branch and aren't included when you merge the changes into the main file.

  1. Click Add your review in the bottom-right corner of the window.
  2. In the Finish your review dialog, select Suggest changes.
  3. Add any general comments you want to make (optional). You can also close out the modal and add comments to designs or layers in the branch.
  4. Select Submit add your review. You'll see a Changes suggested badge next to the branch name in the toolbar.

  

  Edit review

  Edit your review to make changes to your comment. If you've made a mistake or want to change your review, you can review the branch again.

  1. Click next to the branch name in the toolbar.
  2. Select Review and merge changes.
  3. Find your review in the left sidebar. Click next to your name.
  4. You'll see a blue border around the comment to show the field is now editable. Click inside the text and make any changes as needed. Click outside the text field to apply your changes.

  

  Review again

  If you've made a mistake or want to change your review, you can review the branch again. You can also use this process to review a branch after your suggested changes have been made by the branch creator.

  1. Click next to the branch name in the toolbar.
  2. Select Review and merge changes.
  3. Click Review again at the bottom of the modal.
  4. Select from Approve or Suggest changes.
  5. Add a comment if needed (optional).
  6. Click Submit to add your review.
• Merge branch into main file

  Who can merge branches

  Only people with an editor role in an organization or workspace can access the branching feature.

  Anyone with can edit access to the main file can merge branches.

  This article covers one step in the branching process:

  Create → Share → Update → Request → Review → Merge → Manage

  When you want to apply your branch changes to the main file, you can merge the branch. If you have multiple branches and contributors, we recommend coordinating merges to reduce errors or disruption.

  If you have view only access to the main file, you will need to request a branch review from someone with edit access.

  If you have edit access to the main file, you can go ahead and merge the branch. You can still choose to request a review from a collaborator.

  Caution: If you have an active memory limit banner in your file, you can't review and merge changes. Figma will disable the Review and merge changes setting. To get updates from the main file or merge a branch, you need to reduce your memory usage.

  Open branch review

  1. Open the branch you want to merge.
  2. Expand the menu next to the file/branch name in the toolbar.
  3. Select Review and merge changes to open the branch review modal.
  4. You may need to review updates from the main file and resolve any conflicts. Click Resolve conflicts to start the process.

  Review changes

  At the moment, you need to merge all updates from the branch into the main file. There isn't a way to select or merge specific changes.

  1. View a list of components, instances, or layers that have been , , or . Figma groups changes by page.
  2. Select an object or page to view changes. You can choose to view these side by side or as an overlay.
  3. View the layer, frame, or component name at the top of the modal.
  4. Use the buttons to:
     • Zoom out
     • Zoom in
     • FIT Zoom to fit
  5. Use and arrows at the bottom to move between changes if there is more than one change.
  6. Click in the top left to go back to the summary.

  Side by side

  Side by side view allows you to see both designs at the same time. This is the default display option.

  • The left side shows what your object looks like before your changes (the main file).
  • The right side shows what that object look will look like after the merge (the branch).

  

  Overlay

  Overlay allows you to compare the before and after by placing them on top of one another.

  • The layer underneath is the element before the branch is merged (the main file).
  • The top on top is the element after the merge (the branch).

  You can drag the toggle left or right to adjust the opacity of the after object.

  

  Merge branch

  Click Merge to apply changes from the branch to the main file. This will also archive the branch.

  Figma will show a notification at the bottom of the screen to confirm the merge. There is an option to add a name and description for the merge in the file's version history.

   

  

  1. Click Edit merge description.
  2. Add a Name for the merge.
  3. Give the merge a Description.
  4. Click Save to apply.

  You can also come back and add or edit this description in the file's version history.

  It’s possible to undo merges and updates by restoring a previous version of the branch or main file. This also applies if you notice something doesn’t look right after a merge or update. Incomplete updates and merges →

• Incomplete merges or updates

  Who can merge branches

  Only people with an editor role in an organization or workspace can access the branching feature.

  Anyone with can edit access to the main file can merge branches.

  This is one step in the branching process. For more information on branching, check out our Guide to branching.

  There are a few steps involved in receiving updates and merging changes. And while uncommon, it’s possible for something to go wrong at one of those steps.

  If it does, you may find yourself in a situation where a merge or update didn't complete. We’re working on improvements that will reduce the chances of this happening.

  In the meantime, there are a few things you can do if something doesn’t look right after a merge or update.

  Issues

  Problem	Solution
  Updates from a previous merge show up as conflicts you still need to resolve. This means a previous update from main didn’t complete.	You have two options available: Repeat the process by resolving the conflicts. Restore the branch ↓ to a version before the failed update. You can restore from the Before update checkpoint in the branch’s version history.
  Changes from the branch have been applied to the main file, but the branch hasn’t been closed.	If all your changes have been successfully applied, you can archive the branch.
  Not all changes from the branch are applied to the main file.	Restore the main file ↓ to a version before the failed merge. Then repeat the merge process.
  You accidentally merged changes from a branch, or want to undo your changes.	You can restore a previous version of the main file ↓.

  Restore an earlier version of a branch

  Tip! You can identify a branch by looking out for this structure in the toolbar:

  File name Branch name

  1. Make sure you have the branch open.

  2. Click on an empty spot in the canvas to deselect any layers.

  3. In the toolbar, click next to the file name.
  4. Select Show Version History.
  5. In the right sidebar, click next to the “Before update” checkpoint.

     

  6. Click next to the version name and select Restore this version.
  7. Click Done in the toolbar to exit version history.

  Restore an earlier version of the main file

  Caution: Restoring a previous version applies to everyone with access to the main file. This won’t preserve any other changes made to the main file, including other branch merges.

  Note: Reversing or undoing a merge won’t restore an archived branch. You’ll need to restore the branch before trying to merge the branch again.

  1. From the main file, click the next to the file name in the toolbar.
  2. Select Show version history to open version history in the right sidebar.
  3. You can identify a merged branch with the Branch merge icon.

     

  4. Select a version before the merged branch. This could be the “Before merge” checkpoint or any other checkpoint.
  5. Click next to the version and select Restore this version.
  6. Click Done in the toolbar to exit version history.

  View a file's version history →

  Restore an archived branch

  1. Click the file/branch name in the toolbar.
  2. Select See all branches to open the branches modal.
  3. Select the Archived tab to view any archived branches.
  4. Click next to the branch you want to restore and select Restore.
  5. You can then switch to the Active tab, hover over the branch and click Open.