Use Source Control with Projects

You can use projects to work with files under source control. Source control stores files in a repository, lets you check files out of the repository to work on and back into it to preserve changes, and lets you see the history of the different versions of files that have been checked in. For more information about using source control in MathWorks products, see Source Control Integration in MATLAB.

Projects integrate with two source control systems, Git™ and Subversion^® (SVN).

To set up a project with source control, use any of these workflows:

Create a new project from an existing repository.
Add an existing project to source control.
Create a new project in a folder already under source control.
Create a new GitHub^® repository for a new or an existing project.

Then, when your project is under source control, you can perform operations from within MATLAB^® such as checking files in and out, running checks, and committing and reverting changes.

Setup Source Control

There are four ways to set up a project with source control.

Create New Project from Existing Repository

Create a new local copy of a project from an existing repository by retrieving files from source control. You can clone a Git repository, or check out files from an SVN repository, or use another source control integration.

To create a new project from an existing repository:

On the Home tab, click New > Project > From Git or New > Project > From SVN. The New Project From Source Control dialog box opens.
If you know your repository location, paste it into the Repository path field.
Otherwise, to browse for and validate the repository path to retrieve files from, click Change.
1. In the dialog box, specify the repository URL by entering or pasting a URL into the field, by selecting from the list of recent repositories, or by clicking the button.
2. Click Validate to check the repository path. If the path is invalid, check the URL against your source control repository browser.
3. If you see an authentication dialog box for your repository, enter login information to continue.
4. If necessary, select a deeper folder in the repository tree. With SVN, you might want to check out from trunk or a branch folder under tags.
5. When you have finished specifying the URL path you want to retrieve, click OK. The dialog box closes and you return to the New Project From Source Control dialog box.
In the Sandbox field, select the working folder where you want to put the retrieved files for your new project. With SVN, use a local folder for best results, because using a network folder is slow.
Click Retrieve.
If your repository already contains a project, the project is ready when the tool finishes retrieving files to your selected sandbox folder.
If your sandbox does not yet contain a project, then a dialog box asks whether you want to create a project in the folder. To create a project, specify a project name and click OK. The Welcome screen appears to help you set up your new project. For more information about setting up a project, see Set Up Project.

If you encounter errors like OutOfMemoryError: Java heap space when cloning large Git repositories, edit your MATLAB preferences to increase the heap size.

On the Home tab, in the Environment section, click Preferences.
Select MATLAB > General > Java Heap Memory.
Move the slider to increase the heap size, and then click OK.
Restart MATLAB.

Add Existing Project to Source Control

If you have an existing project, you can add it to Git or SVN source control.

To add a project to source control:

On the Project tab, in the Source Control section, click Use Source Control. The Source Control Information dialog box opens.
Click the Add Project to Source Control button. The Add to Source Control dialog box opens.
In the Source control tool list, select the right tool for your repository. If you choose Git, then skip step 4 and go straight to step 5.
If you are using an SVN remote repository, to specify an existing repository, click the button to browse for your repository, paste a URL into the field, or use the list to select a recent repository.
Click Validate to check the path to the selected repository, and then click OK.
Click Convert to finish adding the project to source control.
The project runs integrity checks.
After the integrity checks run, click Open Project to return to your project.
The project displays details of the current source control tool and the repository location.
If you created a new repository, select the Files > Modified view and click Commit to commit the first version of your files to the new repository. In the dialog box, enter a comment if you want, and click Submit.

If you want to merge branches with Git, you need to follow additional setup steps. For more information, see Set Up Git Source Control.

If you want to use a version of SVN other than the built-in version, see Set Up SVN Source Control.

Create New Project in Folder Already Under Source Control

If you create a new project from a folder that is already under source control, MATLAB automatically adds the new project to source control. For more information about creating a project from a folder, see Create Projects.

Create New GitHub Repository

Creating a GitHub repository adds Git source control to your new or existing project. The GitHub repository you create becomes the project remote repository. To create a GitHub repository, you must have a GitHub account.

To create a blank project and a GitHub remote repository:

On the Home tab, click New > Project > From Git.
Select New > GitHub Repository. In the GitHub dialog box, enter your User name and Personal access token. Fill the Repository name and Description fields and click Create.
MATLAB creates a new public GitHub repository and populates the Repository path field with information in the https://github.com/myusername/mynewrepository format.
In the Sandbox field, specify the location for your sandbox. The selected folder must be empty. Click Retrieve to create the sandbox.
To confirm the project name and creation, click OK.

After creating the GitHub repository and sandbox, add your files to the sandbox. Commit the first version of your files to your local repository, then push all modifications to your remote GitHub repository. For more information, see Use Git in MATLAB.

Tip

If you want to create a remote GitHub repository for an existing project, share your project to GitHub instead.

With your project loaded, on the Project tab, select Share > GitHub. For detailed instructions, see Publish on GitHub in Share Projects.

Perform Source Control Operations

Retrieve Versions and Checkout Project Files

This table shows how to check for modified project files, update revisions, get and manage file locks, and tag project files.

Action	Procedure
Refresh status of project files.	To check for locally modified files, on the Project tab, in the Source Control section, click Refresh. Refreshing queries the local sandbox state and checks for changes made with another tool outside of MATLAB. For more information, see Work with Files Under SVN in MATLAB or Use Git in MATLAB.
Check for modifications in project files.	To find out if there is a new version of the project in the repository, in the Files view, right-click the file and select Source Control > Check for Modifications. With SVN, this option contacts the repository to check for external modifications. The project compares the revision numbers of the local file and the repository version. If the revision number in the repository is larger than that in the local sandbox folder, then the project displays (not latest) next to the revision number of the local file.
Update all project files.	Using SVN, to get the latest changes of all project files, go to the Project tab, and in the Source Control section, click Update. The project displays a dialog box listing all the files that have changed on disk. You can control this behavior using the project preference Show changes on source control update. For more information, see Work with Files Under SVN in MATLAB. Using Git, to get the latest changes for all project files from a source control repository and merge them into your current branch, go to the Project tab, and in the Source Control section, click Pull. To get changes and merge manually, on the Project tab, in the Source Control section, click Fetch. This updates all of the origin branches in the local repository. When you click Fetch, your sandbox files are not changed. To see the changes from others, merge in the origin changes to your local branches. For more information, see Use Git in MATLAB.
Update revision for selected project files.	To update a selected set of files, in the Files view, right-click the files, and select the Source Control > Update command for the source control system you are using. For example, if you are using SVN, select Source Control > Update from SVN to get fresh local copies of the selected files from the repository.
Clear SVN login information.	To clear any stored login credentials, on the Project tab, in the Source Control section, click Clear Login.
Get SVN file locks.	To get SVN file locks, in the Files view, select the files that you want to check out. Right-click the selected files and select Source Control > Get File Lock. A lock symbol appears in the SVN source control column. Other users do not see the lock symbol in their sandboxes, but they cannot get a file lock or check in a change when you have the lock. To view or break locks, on the Project tab, click Locks. Get File Lock is only for SVN. Git does not have locks.
Manage SVN repository locks.	To manage global SVN locks for a repository, on the Project tab, in the Source Control section, click Locks. For more information, see Get SVN File Locks.
Tag versions of project files.	To identify specific revisions of all project files, on the Project tab, in the Source Control section, click Tag. Specify the tag text and click OK. The tag is added to every project file. Errors appear if you do not have a `tags` folder in your repository. For more information, see Set Up SVN Source Control.

Review Changes in Project Files

You can review changes in project files using the Files > Modified view. This table shows how to view the list of modified project files, review the history of a file, and compare two files' revisions.

Action	Procedure
View modified project files.	In the Files view, select the *Modified (number of files)* tab. The Files > Modified view is visible only if you are using source control with your project. Tip Use the List layout to view files without needing to expand folders. You can identify modified or conflicted folder contents using the source control summary status. In the Files view, folders display rolled-up source control status. This makes it easier to locate changes in files, particularly conflicted files. You can hover over the source control status (for instance, the Git or SVN column) for a folder to view a tooltip displaying how many files inside are modified, conflicted, added, and deleted.
Update modified files list.	To update the modified files list, on the Project tab, in the Source Control section, click Refresh.
View revision history.	In the Files view, right-click a file and select Source Control > Show Revisions. To browse and compare files within committed SVN change sets, on the Project tab, in the Source Control section, select Show Log. In the File Revisions dialog box, select a revision to view a list of modified files. Right-click files in the lower list to view changes or save revisions.
Compare revisions.	In the Files view, right-click a file and select Compare > Compare to Ancestor to run a comparison against the local repository (Git) or against the last checked-out version in the sandbox (SVN). The Comparison Tool displays a report. To compare other revisions of a file, select Compare > Compare to Revision. To view a comparison report, select the revisions you want to compare and click Compare Selected. Or, select a revision and click Compare to Local. For more information, see Compare Files and Folders and Merge Files.

Project Definition Files. The files in the resources/project folder are project definition files generated when you first create or make changes to your project. The project definition files enable you to add project metadata to files without checking them out. Some examples of metadata you can change this way are shortcuts, labels, and project descriptions. Project definition files also specify the files added to your project. These files are not part of the project.

Any changes you make to your project generate changes in the resources/project folder. These files store the definition of your project in XML files whose format is subject to change.

You do not need to view project definition files directly, except when the source control tool requires a merge. The files are shown so that you know about all the files being committed to the source control system.

Starting in R2020b, the default project definition file type is Use multiple project files (fixed-path length). To change the project definition file management from the type selected when the project was created, use matlab.project.convertDefinitionFiles. matlab.project.convertDefinitionFiles preserves the source control history of your project.

Warning

To avoid merge issues, do not convert the definition file type more than once for a project.

For releases before R2020b, if you want to change the project definition file management from the type selected when the project was created:

On the Home tab, in the Environment section, click Preferences. Select MATLAB > Project and in the New Projects section, select one of the options under Project definition files:
- Use multiple project files - Helps to avoid file conflicts when performing merge on shared projects
- Use multiple project files (fixed-path length) - Is better if you need to work with long paths
- Use a single project file (not recommended for source control) - Is faster but is likely to cause merge issues when two users submit changes in the same project to a source control tool
Create a project archive file (.mlproj). For more information, see Share Projects or export.
Create a new project from the archived project. For more information, see Create Projects.

To stop managing your folder with a project and delete the resources/project folder, see matlab.project.deleteProject.

Run Project Checks

To run checks for a project, on the Project tab, click the down arrow to expand the Tools gallery. Under Project Checks, click Check Project. The project checks for problems with project integrity such as missing files, unsaved files, or files not under source control. A dialog box reports the results. You can click for details and follow prompts to fix problems.

If you want to check for required files, click Dependency Analyzer to analyze the dependencies of the modified files. Use the dependency tools to analyze the structure of your project.

For details on problems the checks can fix, see Work with Derived Files in Projects, and Analyze Project Dependencies.

Commit Modified Project Files

After reviewing changes and running project checks, you are ready to commit your modified project files to source control. This table shows how to commit modified project files.

Action	Procedure
Commit all modified files to source control.	In the Files view, select the *Modified (number of files)* tab. On the Project tab, in the Source Control section, click Commit. Enter comments in the dialog box, and click Submit. If you are using Git source control, this commits to your local repository. If you are using SVN source control, this commits changes to your repository. A message appears if you cannot commit because the repository has moved ahead. Before you can commit the file, you must update its revision up to the current HEAD revision. If you are using Git source control, click Pull. If you are using SVN source control, click Update. Resolve any conflicts before you commit.
Commit selected files to source control.	In the Files view, select the files, right-click, and select Source Control > Commit. If you commit individual files, you risk not committing the related project definition files that keep track of your files. To avoid this, commit all modified files.
Push project files with Git.	To send local commits to the remote repository, on the Project tab, in the Source Control section, click Push. A message appears if you cannot push your changes directly because the repository has moved on. Click Fetch to fetch all changes from the remote repository. Merge branches and resolve conflicts, and then you can push your changes. For more information, see Use Git in MATLAB.
Push empty project folders with Git.	You cannot add empty folders to Git source control, so you cannot click Push and then clone an empty folder. You can create an empty folder in a project, but if you push changes and then sync a new sandbox, the empty folder does not appear in the new sandbox. Instead, run Check Project, which creates the empty folder for you. Alternatively, to push empty folders to the repository for other users to sync, create a `gitignore` file in the folder and then push your changes.
Create Git stashes.	Git stashes store uncommitted changes for later use. To create a stash, on the Project tab, in the Source Control section, click Stashes. The Stashes dialog box opens. Click New Stash to create a stash containing your currently modified files. For more information, see Store Uncommitted Changes Using Git Stashes.
Create a branch with Git.	To create a branch, on the Project tab, in the Source Control section, click Branches. The Branches dialog box appears, where you can view, switch, create, and merge branches. Select a source for the new branch. Click a node in the Branch Browser diagram, or enter a unique identifier in the Source text box. You can enter a tag, branch name, or a unique prefix of the SHA1 hash (for example, `73c637`) to identify a specific commit. Leave the default values to create a branch from the head of the current branch. Enter a name in the Branch name text box and click Create.
Switch, compare, save, and merge branches with Git.	To switch, compare, save, and merge branches, on the Project tab, in the Source Control section, click Branches. The Branches dialog box appears, where you can view, switch, create, and merge branches. For more information, see Branch and Merge with Git.
Resolve conflicts.	If you and another user change the same file in different sandboxes or on different branches, a conflict message appears when you try to commit your modified files. Extract conflict markers if necessary, compare the differences causing the conflict, and resolve the conflict. If you have several conflicted files, see Determine Order for Resolving Conflicts Using Dependency Analyzer. Look for conflicted files in the Files > Modified view. Identify conflicted folder contents using the source control summary status. Folders display the rolled-up source control status. This makes it easier to locate changes in files, particularly conflicted files. You can hover over the source control status for a folder to view a tooltip displaying how many files inside are modified, conflicted, added, and deleted. Tip Use the List layout to view files without needing to expand folders. Check the source control status column (Git or SVN) for files with a red warning symbol, which indicates a conflict. Right-click the conflicted file and select View Conflicts to compare versions. A comparison report opens showing the differences between the conflicted files. When you have resolved the changes and want to commit the version in your sandbox, right-click the file and select Source Control > Mark Conflict Resolved. For Git, the Branch status in the Git pane changes from MERGING to SAFE. Select the Files > Modified view to check changes.

Revert Changes

This table shows how to revert changes in project files. For more information about reverting changes, see Commit or Revert Changes to Modified Files under SVN Source Control and Use Git in MATLAB.

Action	Procedure
Revert local changes.	To release locks and revert to the version in the last sandbox update (that is, the last version you synchronized or retrieved from the repository), in the Files view, right-click the files to revert and select Source Control > Discard Local Changes and Release Locks. To discard local changes when using Git, right-click a file and select Source Control > Revert Local Changes. To remove all local changes, click Branches in the Git pane and click Revert to Head.
Revert a file to a specified revision	To revert a file to a specified revision, right-click a file and select Source Control > Revert using SVN or Source Control > Revert using Git. In the Revert Files dialog box, choose a revision to revert to. Select a revision to view information about the change, such as the author, date, log message. Click Revert. If you revert a file to an earlier revision and then make changes, you cannot commit the file until you resolve the conflict with the repository history.
Revert a project to a specified revision (SVN source control only).	To revert a project to a specified revision, on the Project tab, in the Source Control section, click Revert Project. In the Revert Files dialog box, choose a revision to revert to. Each revision in the list is a change set of modified files. Select a revision to view information about the change such as the author, date, and the log message. Once you have chosen a revision and are satisfied that the information is correct, click Revert.

Action

Procedure

Revert local changes.

To release locks and revert to the version in the last sandbox update (that is, the last version you synchronized or retrieved from the repository), in the Files view, right-click the files to revert and select Source Control > Discard Local Changes and Release Locks.

To discard local changes when using Git, right-click a file and select Source Control > Revert Local Changes. To remove all local changes, click Branches in the Git pane and click Revert to Head.

Revert a file to a specified revision

To revert a file to a specified revision, right-click a file and select Source Control > Revert using SVN or Source Control > Revert using Git.

In the Revert Files dialog box, choose a revision to revert to. Select a revision to view information about the change, such as the author, date, log message. Click Revert.

If you revert a file to an earlier revision and then make changes, you cannot commit the file until you resolve the conflict with the repository history.

Revert a project to a specified revision (SVN source control only).

To revert a project to a specified revision, on the Project tab, in the Source Control section, click Revert Project. In the Revert Files dialog box, choose a revision to revert to.

Each revision in the list is a change set of modified files. Select a revision to view information about the change such as the author, date, and the log message.

Once you have chosen a revision and are satisfied that the information is correct, click Revert.

Work with Derived Files in Projects

In general, it is a best practice to omit derived and temporary files from your project or exclude them from source control. To check for derived or temporary files, on the Project tab, click the down arrow to expand the Tools gallery. Under Project Checks, click Check Project. If you add the slprj folder to a project, the project checks advise you to remove this from the project and offer to make the fix. The derived files check is only enabled if the project is under source control.

It is also a best practice to exclude derived files such as .mex*, the contents of the slprj folder, sccprj folder, or other code generation folders from source control, because they can cause problems. For example:

With a source control system that can do file locking, you can encounter conflicts. If slprj is under source control and you generate code, most of the files under slprj change and become locked. Other users cannot generate code because of file permission errors. The slprj folder is also used for simulation via code generation, so locking these files can have an impact on a team. The same problems arise with binaries, such as .mex*.
Deleting slprj is often required. However, deleting slprj causes problems such as “not a working copy“ errors if the folder is under some source control tools (for example, SVN).
If you want to check in the generated code as an artifact of the process, it is common to copy some of the files out of the slprj cache folder and into a separate location that is part of the project. That way, you can delete the temporary cache folder when you need to. Use the packNGo (MATLAB Coder) function to list the generated code files, and use the project API to add them to the project with appropriate metadata.
The slprj folder can contain many small files. This can affect performance with some source control tools when each of those files is checked to see if it is up-to-date.

Find Project Files With Unsaved Changes

You can check your project for files with unsaved changes. On the Project tab, click the down arrow to expand the Tools gallery. Under Project Checks, click Show Unsaved Changes.

In the Unsaved Changes dialog box, you can see the project files with unsaved changes. Project only detects unsaved changes edited in the MATLAB and Simulink^® editors. Manually examine changes edited in other tools. If you have referenced projects, files are grouped by project. You can save or discard all detected changes.

Manage Open Files When Closing a Project

When you close a project, if there are files with unsaved changes, a message prompts you to save or discard changes. You can see all files with unsaved changes, grouped by project if you have referenced projects. To avoid losing work, you can save or discard changes by file, by project, or globally.

To control this behavior, on the Home tab, in the Environment section, click Preferences. Go to MATLAB > Project and in the Project Shutdown section, select or clear the check box labeled Check for open project models and close them, unless they are dirty.