Organize Projects into Components Using References and Git Submodules

This example shows how to organize large projects into components using references and Git™ submodules.

By organizing your project into components, you can facilitate component reuse, team development, unit testing, and independent release of components.

In this example, you create a new component from an existing project folder. You also reuse other projects as referenced projects. For a project under Git source control, this example shows how to populate a reference project by using Git submodules. For more information, watch How to Organize Large Projects into Components (3 min, 32 sec).

Create Referenced Project

Open the project you want to organize into components.

In a large project, you can create a new component from an existing folder in your project.

Right-click the folder you want to use to create a new project and select Extract to Referenced Project.
In the Extract to Referenced Project dialog box, specify the New Project Name and New Project Location fields, and then click Extract.

MATLAB® removes the folder from the parent project, creates a new component project, and adds it as a referenced project.

Add Referenced Project

To reuse other components in the top-level project, you can add them as referenced projects.

On the Project tab, in the Environment section, click References.
Navigate to the Referenced Project Location and select the PRJ file.
Click Add.

MATLAB adds a new component project to the top-level project.

Creating or adding a referenced project modifies the parent project metadata. To make changes available to other project users, commit and push to the remote.

On the Project tab, in the Source Control section, click Commit.
Enter a comment and click Submit.
Click Pull and Push.

Use Git Submodules with Referenced Projects

For a project under Git source control, a Git submodule helps you keep commits and changes in a repository separate from the parent repository. Use Git submodules when you want your parent repository to point to a specific commit in another external repository. Submodules are static and are typically used for utilities and shared libraries. When you update the parent repository, submodules do not update automatically.

To populate a new referenced project using Git submodule, clone an external repository.

On the Project tab, in the Source Control section, click Submodules.
To clone an external Git repository as a submodule, click Add.
Specify the Remote URL and Path. Click OK.

The top-level project now points to the commit of the submodule specified by Index.

Add the submodule that you cloned as a referenced project using the steps described in Add Referenced Project.

If you cloned several submodules, use project integrity checks to ensure all submodules are referenced projects.

On the Project tab, expand the Tools gallery and click Check Project.

Make Changes to Submodules

To make changes in a submodule:

Open the corresponding referenced project as a top-level project.
In the References view, select the referenced project. On the References tab, click Open Project.
Make changes.
On the Project tab, in the Source Control section, click Commit. Enter a comment and then click Submit.
To make changes available to other users, push to the submodule remote repository. In the Source Control section, click Pull and then Push.

Update Submodule Index

The top-level project can now see all of the recent changes, but still points to the head commit from when you first cloned the submodule. The commit stored in Index remains the same.

To update the index to point to the latest commit:

On the Project tab, in the Source Control section, click Submodules.
In the Submodules dialog box, click Branches.
In the Branches dialog box, select the branch and the commit to which you want your top-level project to point. Click Switch. The submodule definition in the top-level repository changes.
Save the submodule definition and update the Index to the newly selected commit. On the Project tab, in the Source Control section, click Commit.
To send the new submodule definition to the top-level remote repository, click Pull and then Push.

The Index now matches the Head.

After you clone or update a Git submodule, it is in detached head state. Before committing any changes to a submodule, switch to the appropriate branch.

On the Project tab, in the Source Control section, click Submodules.
In the Submodules dialog box, click Branches.
In the Branches dialog box, select the branch and then click Switch.

For more information about branch merges and updating submodules, see Add Git Submodules.