--- title: "Working with subdesigns" slug: "working-with-subdesigns" description: "Commit, push, and pull design file changes with Allspice Desktop. Resolve conflicts, discard changes, switch branches, and remove projects from the app." tags: ["allspice desktop", "version control"] updated: 2026-10-30T13:50:31Z published: 2026-10-30T13:50:31Z canonical: "learn.allspice.io/working-with-subdesigns" --- > ## Documentation Index > Fetch the complete documentation index at: https://learn.allspice.io/llms.txt > Use this file to discover all available pages before exploring further. # Working with subdesigns > **Beta:** Allspice Desktop is in beta and available only to select organizations, as of October 30, 2026. Features, supported systems and these instructions may change between releases, and some features may be incomplete. If your organization doesn't see the **Desktop App** button in Allspice Hub, it isn't part of the beta yet. Contact your Allspice account team to learn more. We welcome your feedback. *Applies to Allspice Desktop v0.2.0 and later. This guide covers the desktop app.* ## What a subdesign is A **subdesign** is a design that lives in its own Allspice project and is used inside a larger design. A power supply, an RF front end, a sensor daughterboard, a standard connector block — any piece you want to design once and reuse across products. Instead of copying those files into every project that needs them, you add the subdesign's project to your top-level project. Your project then records two things: - **which project** the subdesign comes from, and - **exactly which version** of it your design is built against. That second point is what makes subdesigns useful. Your top-level design is always tied to a specific, known version of every block it contains. When the block's owner publishes a change, your project doesn't move on its own — it keeps building against the version you chose until you decide to take the new one. Everyone who opens your project gets the same versions you did. A subdesign appears in your project folder as a normal folder of design files, named after the project it came from. Your ECAD tool reads it like any other folder on disk. > **Best practice: don't edit a subdesign's files in place.** A subdesign's folder is a copy of another project, held at the version your design records. Change it where it comes from — open that project on its own, make the change there, and then bring it into your design with **Update**. Work done directly in the subdesign's folder isn't part of either project, and the next update replaces it. > **Adding a shared component library?** Same feature, same steps — see *Also useful: component libraries* at the end of this guide. Three words appear throughout the app and this guide: | Term | What it means | | --- | --- | | **Project** | A repository on Allspice — your top-level design, or a reusable block of its own. | | **Subdesign** | Another project that your project uses, at a version your project records. | | **Pin** | To set which branch of a subdesign your project follows. | --- ## Before you start You need: - **Allspice Desktop v0.2.0 or later**, signed in to your Allspice server. The version is shown at the bottom-left of the window. - **Your top-level project cloned** in Allspice Desktop and open on a branch you're allowed to push to. If the branch is protected, the app tells you and you'll need to switch to another branch. - **Read access to the project you want to add.** You can only add a project you can already see on Allspice — the picker shows exactly the projects your account has access to. - **The subdesign's design files already pushed to Allspice.** A project that only exists on your machine can't be added as a subdesign. --- ## Where subdesigns live in the app Open a project in Allspice Desktop. Below the project's status, there's a **SUBDESIGNS** section. - When the project has no subdesigns, the section explains what a subdesign is. - When it has some, each one is a row with its **name**, the **branch it follows** underneath, and a **status badge** on the right showing whether it's current. - The **…** button to the right of the **SUBDESIGNS** heading holds the actions for the whole list: **Add subdesign** and **Update all**. - The **…** button on each row holds the actions for that one subdesign: **Update**, **Pin** and **Remove**. --- ## Add a subdesign to your design ### Step 1 — open the Subdesigns menu On your top-level project's page, click the **…** button next to the **SUBDESIGNS** heading, then select **Add subdesign**. ![The Subdesigns section of a project with no subdesigns, with the … menu open on Add subdesign](https://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/01-add-subdesign-menu(1).png) ### Step 2 — choose the project to add The **Add subdesign** dialog lists the projects on Allspice that you have access to. Type in the search box to narrow the list by project or organization name, select the project you want, then click **Add subdesign**. ![The Add subdesign dialog, searching for a project and selecting one from the list](https://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/02-choose-project.png) Two entries in the list can't be selected, and the dialog says why: - **This project** — a project can't contain itself. - **Already a subdesign** — that project is already in your design. ### What the app does When you confirm: - It downloads the project's files into a **new folder at the top of your project folder, named after the project**. For example, adding `AllSpice/demo-lib` creates a `demo-lib` folder. - It records the subdesign as following that project's **default branch**, at the newest version on that branch at this moment. - The new subdesign appears in the **SUBDESIGNS** list, and the addition appears as a change waiting to be committed. > **Note:** The app always names the folder after the project. If a folder with that name already exists in your project, the subdesign can't be added — rename or remove the existing folder first. --- ## Commit and push the change Adding, updating, pinning or removing a subdesign is a **change to your design**, exactly like editing a schematic. It isn't shared with anyone until you commit it and push it. ### Step 1 — commit The change appears on the project page under **1 SUBDESIGN CHANGED**, in its own list, separate from changed files. The row shows the subdesign's name, the branch it follows, and what kind of change it is — **New**, **Updated** or **Deleted**. Make sure the change is selected, type a short message describing it (for example "Add demo-lib power stage"), and click **Commit**. ![The project page with one changed subdesign selected, a commit message typed, and the Commit button](https://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/03-commit-change.png) ### Step 2 — push The commit is now saved on your machine only. Click **Push** to send it to Allspice. ![The project page after committing, showing 1 commit to push and the Push button](https://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/04-push-commit.png) Once pushed, anyone who pulls your project gets the same subdesign at the same version. > **Changed your mind?** Select the change and click **Discard** before committing. The subdesign goes back to the way it was at your last commit. Discarding can't be undone. --- ## Choose which branch a subdesign follows (pin) A subdesign follows one branch of its project. That branch decides what **Update** gives you — it is the line of work you want to take changes from. Your design still sits on a specific version of that branch; following a branch never moves your design on its own. A new subdesign follows its project's **default branch**. Pin it to a different branch when, for example, the block's owner stages work on `develop` and you want to build against released work on`main`, or the opposite — you're developing alongside them and want their in-progress work. ### Step 1 — open the subdesign's menu Click the **…** button on the subdesign's row and select **Pin**. ![A subdesign row with its … menu open, showing Update, Pin and Remove](https://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/05-subdesign-menu-pin.png) ### Step 2 — choose the branch The **Pin subdesign to a branch** dialog lists the branches of the subdesign's project. Choose one and click **Pin**. ![The Pin subdesign to a branch dialog with the branch list open on main and develop](https://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/06-pin-branch-dialog.png) The app moves the subdesign to the newest version on the branch you chose, and the branch name under the subdesign's name changes to match. From then on, **Update** follows that branch. Pinning is a change to your design: **commit and push it** like any other. --- ## Update to the newest version of a subdesign When a subdesign's owner pushes work to the branch you follow, the subdesign's badge changes to **Behind *N*** — your design is *N* versions behind that branch. It keeps using the version you're on until you choose to move. ### Update one subdesign Click the **…** button on the row and select **Update**. The app moves the subdesign to the newest version on its branch. ![A subdesign showing Behind 2 with its … menu open on Update](https://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/07-behind-update.png) ### Update every subdesign at once Click the **…** button next to the **SUBDESIGNS** heading and select **Update all**. Every subdesign that is behind moves to the newest version on the branch it follows. The option is unavailable when nothing is behind. ### After the update The change appears in your changed-subdesigns list as **Updated**, with how many new commits it brings in. Review the result in your ECAD tool, then **commit and push** so your team builds against the same version. > **Good practice:** Update deliberately, not reflexively. A pulled-in change to a shared block can affect your schematic or layout — update when you have time to open the design and check it. --- ## Getting the subdesigns your teammates added You never have to download subdesigns yourself. - **When you open a project**, the app downloads its subdesigns, and any subdesigns inside them. - **After you pull**, or **switch branches**, the app checks out the subdesign versions that branch records — so your folders always match the design you're looking at. If a teammate adds a block and pushes, you simply pull, and the folder appears in your project at the version they committed. --- ## Remove a subdesign Click the **…** button on the subdesign's row and select **Remove**, then confirm. This deletes the subdesign's folder and its files from your project folder. It does not affect the subdesign's own project on Allspice. Like every other subdesign change, the removal has to be **committed and pushed**. > If you want to put a different project in the same folder name, commit the removal first, then add the new subdesign. --- ## Reference: status badges Each subdesign row carries a badge that tells you how your version compares with the branch it follows. The app re-checks Allspice while the window is in focus, so the badge stays current while you work. | Badge | What it means | What to do | | --- | --- | --- | | **Up to date** | Your design uses the newest version on the branch this subdesign follows. | Nothing. | | **Behind *N*** | The branch has *N* newer commits than the version your design uses. | **Update** when you're ready to take them. | | **Pinned** | The subdesign is held at a fixed version and doesn't follow a branch. | **Pin** it to a branch if you want update checks. | | **Missing** | The subdesign's files aren't on your machine yet. | Reopen the project; the app downloads them. | Other badges appear only when something needs attention — see *Troubleshooting*. --- ## Troubleshooting ### Badges that mean something is wrong | Badge | What it means and what to do | | --- | --- | | **Needs checkout** | The files on your machine are at a different version than your design records. Reopen the project to check out the recorded version. | | **Unreachable** | The app couldn't reach Allspice to check the subdesign. Check your network or VPN connection. | | **Unresolved** | Allspice rejected the check — usually you no longer have access to the subdesign's project. Ask its owner for access. | | **External** | The subdesign comes from somewhere other than your Allspice server. The app shows it but doesn't manage it; update and pin aren't available. | | **Invalid** | The subdesign's address can't be read, or no version is recorded. Contact whoever added it, or remove and re-add it. | | **Missing** | If a subdesign stays **Missing** after you reopen the project, check your network or VPN connection, and that you still have access to its project on Allspice. | ### Messages the app shows | What you see | What it means and what to do | | --- | --- | | *"That folder name is already in use in this project."* | Your project already has a folder named after the project you're adding. Rename or remove it first. | | *"A subdesign was removed from this folder. Commit that change first…"* | You removed a subdesign and are adding another in the same place. Commit the removal, then add. | | *"A subdesign can't include itself, directly or through other subdesigns."* | The project you picked already contains your project somewhere in its own subdesigns. Pick a different project. | | *"This subdesign is not on Allspice."* | The subdesign's project no longer exists on the server, or was renamed or moved. Check it on Allspice. | | *"This subdesign does not follow a branch."* | It's held at a fixed version. Use **Pin** to set a branch, then **Update**. | | *"{branch} is protected. Switch to another branch to make changes."* | You can't push subdesign changes to this branch. Switch to a working branch, make the change there, and open a pull request on Allspice. | --- ## Also useful: component libraries The same feature handles a second, very common case: **keeping a shared component library inside a design at a known version.** A component library isn't really a subdesign — it's a repository of parts, symbols and footprints that your designs draw from, and that Allspice also uses when rendering your design. But it's a dependency of your design in exactly the same sense, so you add it exactly the same way: open the **…** menu next to **SUBDESIGNS**, select **Add subdesign**, and pick the library's project. Doing so gives you the same benefits: - Your design records **which version of the library** it was built against, so a board that built cleanly last quarter still resolves to the same parts today. - Everyone on the team, and every render on Allspice, uses **the same library version** you do. - When the library is updated, your project shows **Behind *N*** — and you take the new parts when you're ready, by clicking **Update**, then committing and pushing. Pin the library to the branch your organization publishes approved parts on, so **Update** always means "take the latest approved parts".