Figma Branching

This help guide goes over how to use Ditto with Figma branching.

‍

Importing Figma Branches

You can import Figma branches into Ditto like any regular Figma file in the web app or the Figma plugin. Just make sure you copy and paste the branch-specific link to the Figma file! It should look something like this:

‍

Once imported, the Figma branch will look and function like any other Ditto project. You’ll be able to tell that a project is connected to a Figma branch if you see the following badge next to the project name:

‍

‍

Note

Working on multiple branches of a Figma file at once in Ditto is currently in beta. This means that if you’ve already imported the main branch of a Figma file into Ditto, you won’t be able to import another branch unless you opt into the beta, and will need to delete the existing project that’s connected to the main branch, and then import your intended branch from scratch as a new project.

To opt in to the beta, just start the process for importing a branch of a Figma file in either the web app or Figma plugin, and follow the prompts:

‍

Merging/Discarding Changes from a Branch

When a branch file gets merged or archived in Figma, the next time you open the Ditto project, you’ll get presented with the following modal, asking what you want to do with the changes made in the Figma branch:

‍

You can select one of two options, depending on what's happened to the Figma branch:

1. The Figma branch has been merged.

• We'll merge the edits from the branch into the Ditto project connected to the main branch of the Figma file. We’ll preserve all existing Ditto metadata and changes, which includes any and all status, tags, edit history, Ditto Components, etc. that were created.

2. The Figma branch has been deleted.

• Choose this option if you’ve archived or deleted the branch in Figma. This will wipe all changes and Ditto metadata created previously. We’ll reset the Ditto project, and you’ll start from scratch with a newly-imported main branch of the Figma file.
  ‍

Once you’ve chosen one of the above options, the Ditto project will now be connected to the main branch of the Figma file. This means you can use the Ditto Figma plugin in the main branch of the Figma file, like usual.

‍

Working with multiple branches (beta)

If you've opted into the beta (see the "Note" at the top of this guide), you'll be able to work on multiple branches in Ditto at once: the main branch of the Figma file, and another non-main branch.

Before continuing with importing the second branch, we strongly suggest doing a resync in the main branch of the Figma file via Ditto's Figma plugin to ensure no work are lost.

Assuming you have the main branch of a Figma file imported into Ditto, when you import another branch, we'll copy over existing work for any text that's the same between the two branches so you can pick up where you left off. This includes: Ditto Components, status, tags, notes, and variants.

‍

Once that second branch is imported, you'll be able to see that on the Projects page, and toggle between the branches once you click into the project.

‍

‍

‍

‍

‍

‍

‍

‍

‍

The Ditto project connected to the main branch of the Figma file will get locked until that second branch gets merged, in order to prevent conflicts or overrides. This means you won't be able to edit text. You will still be able to see all text information, change history, etc:

‍

When the branch gets merged or discarded in Figma, you'll get prompted to confirm which happened in Ditto.

If the Figma branch has been merged, Ditto will merge any copy changes back into the project corresponding to the main branch, and unlock it. The project corresponding to that second branch will then be "archived," so you can refer back to it later.

‍

If the Figma branch has been discarded, we'll delete that branch project.

‍

Note: If there’s additional support for Figma branching you'd like to see, we’d love to hear from you. :)

‍