Projects and Source Control

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

Written against MATLAB R2026b. Projects, the Project and Source Control panels, the Dependency Analyzer and the git functions belong to the MATLAB desktop, so GNU Octave cannot run any of this page; every statement about MATLAB behaviour is checked against the R2026b documentation and every listing is marked "not run here". The section’s reference scenario (see the heatflow scenario) is itself a project, heatflow/, so this page also describes how to organise it.

A MATLAB project is the documentation’s tool for managing a body of work as it grows: MATLAB and Simulink files, data, tests, reports and generated files in one place. Without one, a code base is held together by the current folder, addpath calls and the memory of whoever wrote them (see Search Path, Startup and Files). A project makes those things explicit and shared.

What a project gives you

From the documentation, a project can:

  • manage the search path while the project is open: its path folders are added when you open it and removed when you close it, so the same code runs the same way for every user;

  • run startup and shutdown files, to set up and clean up an environment (open a connection, set a random seed, install package dependencies);

  • hold shortcuts to frequent tasks, such as opening a file or running a script;

  • classify files with labels; the built-in Test label identifies the test suite, which makes it easy to run the tests on a CI server;

  • find the files and dependencies the project needs, with the Dependency Analyzer;

  • run project checks for shadowed files and files with unsaved changes;

  • work with source control (Git and SVN) from the Project panel;

  • reuse code through referenced projects, and templates standardise the folder layout of new projects.

For heatflow, that means a path with src (holding the +heatflow namespace folder, see Namespaces and Class Folders), a startup file that fixes the random seed, a shortcut that runs the runHeatflow script, and the Test label on the files in tests.

Source: MATLAB documentation: Create Projects

Creating a project

Interactively. On the Home tab choose New > Project, or New Project in the Project panel. In the Create Project dialog give a name and select the existing folder; MATLAB adds all its files and folders to the project. If the folder you pick is empty, MATLAB creates a project with a path folder and a test folder, and optionally a local Git repository (since R2026b). A setup guide then asks for the project name and description (step 1 of 4), the folders to put on the project path (step 2), and the startup and shutdown files (step 3); the final step applies the setup. Test folders can be added from this guide (since R2026b). You can turn off the guide that appears at every opening in the project settings.

Programmatically. The recommended-workflow page of the documentation gives this example (written with the names of heatflow here). It creates a project whose definition is in the TOML format, adds two folders to the path and a startup file:

proj = matlab.project.createProject(Name="heatflow", ...
                                    Folder=pwd, ...
                                    DefinitionFilesType="Toml");
addPath(proj, "src");
addPath(proj, "tests");
addStartupFile(proj, "startup.m");

Not run here. The project object proj also has functions to add and remove files, labels, shortcuts and references; currentProject returns the project that is open. A project is closed with close(proj), and openProject opens an existing one.

Source: MATLAB documentation: Develop and Share Software in MATLAB

Where a project stores its definition

A project is described by project definition files. There are two kinds.

Aspect Multiple XML files matlab.toml

Location

The resources/project folder (a .SimulinkProject folder in older projects)

One file in the project root

Readability

XML, a format "subject to change"; you rarely open it, except for a merge

A readable TOML text file you can edit in the MATLAB editor

File membership

Each file is recorded as part of the project (addFile, removeFile)

By default every file in the root folder is a project file; addFile and removeFile still add and remove files from source control

Labels

Applied file by file

Associated with file patterns, so they apply automatically

Package dependencies

Not supported in the conversion (a startup file installs them)

Declared with version constraints and installed from the configured repositories when the project opens

Starting in R2026b the default type for a new project is still multiple XML files; the TOML format is opt-in (MATLAB > Project in the settings, New Projects, Project definition files). To convert an existing project use the Definition file type setting in the project settings, or matlab.project.convertDefinitionFiles. The documentation says the conversion keeps user data, files, source control history, shortcuts and the startup and shutdown tasks, but not label data and single-valued categories (these become multi-valued), and it warns not to convert the same project more than once, to avoid merge problems. Store the project under source control before converting.

A heatflow definition in TOML, built from the syntax examples in the documentation (the dependency identifier below is a placeholder; real ones are the UUIDs of the packages):

name = "heatflow"

[folders]
path = [
    "src",
    "tests",
]

[dependencies]
unitsKit = {version = ">=1.5", id = "00000000-0000-0000-0000-000000000000"}

[project.shortcuts]
"Run heatflow" = {path = "src/runHeatflow.m"}

Not run here. A project can also be created from scratch by creating a text file named matlab.toml in a folder: this makes an unnamed project containing all the files in the folder, and all properties of the file are optional. Open it as text from the Files panel (double-clicking opens the project instead). The complete list of properties is in the matlab.toml reference page (not reached for this page); the file is validated by MATLAB, which reports invalid syntax, invalid data and missing files, and the Project Issues panel reports problems after a conversion. The TOML format is easier to review in a pull request, because a change to the path or to a label is a few visible lines rather than a changed XML file. Note that this is a TOML project, not the mpackage.json of a package; see Packages and the MATLAB Package Manager for the difference.

Source: MATLAB documentation: MATLAB Projects TOML Format (.toml)

Path, startup and shutdown files, shortcuts and labels

  • Path. The folders you list are put on the MATLAB search path when the project opens and removed when it closes. Adding the folder with its subfolders is a single action in the setup guide. This replaces the addpath(genpath(...)) lines that older code carries (see the pitfalls on the path page).

  • Startup and shutdown. The files run from the top down, so the order can matter; use the arrow buttons to reorder. A shutdown file should undo what the startup file did. An example of a heatflow startup file:

% startup.m: runs when the heatflow project opens
rng(0, "twister")
format short
disp("heatflow project ready")

Not run here.

  • Shortcuts. A shortcut runs a file or an action from the Project tab; shortcuts can be grouped and are stored in the definition (in the TOML file under project.shortcuts).

  • Labels. A label classifies a file. A built-in label, Test, identifies the test files so that a CI job can run them; a category can hold several labels. In a TOML project the test folders and the labels are applied by pattern; files with the Test label belong in a test folder.

Dependency analysis

Three tools answer "what does this code need?":

Tool What it reports

inmem

After clear functions and a run of the function, inmem lists the program files that were loaded, and [mfiles, mexfiles] = inmem adds MEX files. Results depend on the arguments used for the run. Functions locked with mlock are not cleared.

matlab.codetools.requiredFilesAndProducts

[fList, pList] = matlab.codetools.requiredFilesAndProducts("myFun.m") returns the files needed and the MathWorks products. The documentation recommends it to find which code files someone else needs to run a file.

Dependency Analyzer

An app (Apps tab, under MATLAB; since R2023a in the Projects page of the documentation) that analyses all files in a folder or a project and shows a dependency graph: which files are required by others, which files fail if you delete one, which called files are missing. In a project, Analyze Project Dependencies finds the required files, lets you resolve problems and add files, and reports the add-ons used.

An example of the programmatic form for heatflow:

[files, products] = matlab.codetools.requiredFilesAndProducts("runHeatflow.m");
disp(files')
disp({products.Name}')

Not run here. The expected result is the list of heatflow files that runHeatflow calls and the single product MATLAB, if the code stays within base MATLAB (this matters because the section’s examples avoid toolboxes; see Toolboxes and Add-On Products). The same check is a quick way to find a toolbox dependency that you added without noticing.

Source: MATLAB documentation: Identify Program Dependencies

Source control

MATLAB has built-in integrations with Git and Subversion. The Source Control panel (since R2025a, replacing the older integration) shows the modified and untracked files of every active working folder, so you can work with several repositories at once; a repository appears there when you change the current folder to it, expand it in the Files panel, open a project under source control, create a matlab.git.GitRepository object, or open the Branch Manager. From the panel you review local changes, add files to source control or to .gitignore, commit or discard, and open the Branch Manager to create, merge and manage branches and to resolve conflicts. Each file shows a status icon.

From a project: on the Project tab, in the Source Control section, Initialize Git Repository, then Add Remote with the URL of the remote (for example on GitHub), then Commit in the Source Control panel. Programmatically, gitrepo and gitclone (both since R2023b) return a matlab.git.GitRepository object:

repo = gitclone("https://github.com/example-org/heatflow");   % placeholder URL
repo = gitrepo;                  % object for the repository of the current folder
repo.CurrentBranch               % the branch you are on
repo.ModifiedFiles               % files with local changes

Not run here. The object has properties such as WorkingFolder, CurrentBranch, LastCommit, Remotes, ModifiedFiles and UntrackedFiles, and methods for the usual operations; creating the object also adds the repository to the Source Control panel.

Setting up Git. The documentation lists steps before using Git with MATLAB. The required one: register MATLAB binary file types with Git, to avoid corrupting them. The list includes .mlx, .mat, .fig, .mlapp, .p, .slx and the MEX extensions, and also files such as .xlsx, .jpg and .pdf. Add them to the repository’s .gitattributes; creating a new project that uses Git creates and fills a .gitattributes for you. A minimal fragment:

* text=auto
*.mlx binary
*.mat binary
*.fig binary
*.mlapp binary
*.p binary

Other steps are recommended or optional: long-path support on Windows, signing commits, SSH authentication or a credential helper, Git LFS for large files, and using MATLAB as the Diff and Merge tool of an external Git client. Git hooks can be run from MATLAB (since R2024a); the supported hooks include pre-commit, commit-msg, post-commit and pre-push.

What to commit. Commit the project definition files (matlab.toml, or the resources/project folder), because they define the project for everybody. Keep generated files, data caches and derived outputs out of the repository (or exclude them with .gitignore), and keep secrets out of it, whatever the format (see Secrets and Protecting Code).

Plain text formats help. Plain text live code (.m, R2025a) and the plain text app format (R2026b) exist so that live scripts and apps can be compared and merged in the ordinary way (see Live Scripts and the Live Editor and Building Apps with App Designer).

Comparing and merging

MATLAB has a Comparison Tool, used for comparing files, folders and project definition files (the documentation has a Compare MATLAB Projects topic), and the Branch Manager has a conflict resolution workflow for Git. A conflicted file shows its type of conflict in a tooltip. For binary files such as .mlx or .mlapp, the line-based Git merge does not apply; MATLAB’s own merge for those files is available when you configure it (see Customize External Source Control to Use MATLAB for Diff and Merge). The simplest rule: keep one author per binary file at a time, and prefer the plain text formats.

Source: MATLAB documentation: Source Control Integration in MATLAB

Pitfalls

  • Converting the definition type twice. The documentation warns against it, to avoid merge problems.

  • Forgetting to commit the definition files. The project is the definition; a repository without it is just a folder.

  • Binary files not registered. Without .gitattributes, Git can alter line endings or try to merge .mlx and .mat files and corrupt them.

  • Relying on a developer’s path. If the code works only because someone has an addpath in their startup.m, other users and CI fail; put the folders in the project path.

  • Shadowed files. Project checks report files with the same name in different path folders; fix them before they change which function runs (see Function Precedence and Name Resolution).

  • Test files in the root. In a TOML project, files with the Test label belong in a test folder.

  • Assuming TOML is the default. In R2026b a new project uses multiple XML files unless you change the setting.

Where older books differ

The older books predate projects and the TOML format (R2026b) and treat code organisation as folders plus addpath, savepath and a hand-written startup.m. They treat version control as something outside MATLAB, or describe the older source-control interface. The folders and startup.m still work, but a project is now the documented way to share a code base, and the Git functions (gitrepo, gitclone, R2023b) and the Source Control panel replace the older integration.

See Also

References