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.

Create Referenced Project from Folder

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.

1. Right-click the folder you want to use to create a new project and select Extract to Reference Project.

2. In the Create Reference Project dialog box, specify the Name and Folder fields, and then click OK.

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

To view the list of project references, on the Project tab, in the Environment section, click References.

Add Project Reference

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

1. On the Project tab, in the Environment section, click New Reference.

2. Navigate to the project you want to reference and select the PRJ file.

3. Click Open.

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.

1. On the Project tab, in the Source Control section, click Commit.

2. Enter a comment and click Commit.

3. 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.

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

1. On the Project tab, in the Source Control section, click Branch Manager.

2. In the left pane of the Branch Manager, in the Submodules section, click the Submodules actions button and select Add Submodule.

3. Specify the URL and Path. Then, click Add.

The Branch Manager lists the submodule in the Submodules section. Click the submodule to see the details.

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

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

Tip: If you cloned several submodules, run the project integrity checks to ensure all submodules are referenced projects.

On the Project tab, in the Environment section, click Project Issues. In the Project Issues panel, in the Checks tab, click Run Checks.

Make Changes to Submodules

To make changes in a submodule project, follow these steps.

1. 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.

2. Verify that the submodule is not in detached head state. On the Project tab, in the Source Control section, click Branch Manager. If the submodule is in detached head state, in the Branch Manager toolstrip, in the Current Branch section, switch to the appropriate branch.

3. Make changes.

4. On the Project tab, in the Source Control section, click Commit. Enter a comment and then click Commit.

5. 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 commit, specified in Index, from when you first cloned the submodule.

To verify this information, in the Branch Manager, in the Submodules section, click the submodule. The commits stored in HEAD and Index are different.

To update the index to point to the latest commit, in the main project, follow these steps.

1. On the Project tab, in the Source Control section, click Commit.

2. To send the new submodule definition to the top-level remote repository, click Pull and then Push.

The Branch Manager now only shows the HEAD commit because the HEAD and index commits match.

Tip: Use the Source Control panel to work with multiple repositories at the same time. For detailed instructions on how to update and modify files in submodules, see Work with Git Submodules in MATLAB.