MATLAB® @ Work

richj@datatool.com 1 www.datatool.com

MATLAB Source Control Using Git

Richard Johnson

Using source control is a key practice for professional programmers. If you have ever broken a program

with a lot of editing changes, you can benefit from source control. If you develop with other

programmers, you need source control. This tutorial provides the basic information that you need to set

up and use Git source control with MATLAB.

Starting with R2014b, source control is included in MATLAB (using Git or

Subversion). Git is harder to learn than Subversion (more concepts and

more commands), but it is growing in popularity and offers some

advantages in use. Git is often faster than Subversion. Git is distributed,

so you can use it effectively even when you are not connected to the

main repository. Git lacks a desirable GUI interface like TortoiseSVN for

Subversion, but this is not an issue for the MATLAB-integrated version.

This tutorial will show you how to setup and use source control in MATLAB using Git. This tutorial uses a

Windows operating system and can run on a stand-alone computer. The process would be similar with

other operating systems or when using a network.

Source control basics The MATLAB Undo feature lets you easily back out editing changes one at a time. It does not let you

easily keep both an older and a newer version. Additionally Undo loses its memory when you close the

file’s editor tab or close MATLAB. Some programmers try to keep an older or a just-in-case version of a

file through renaming, often by creating versions a, b, c or 1, 2, 3. Having such multiple versions quickly

becomes a headache.

Source (aka version) control is a solution for working with multiple file versions. It provides a graceful

way to keep old versions, to compare versions, and to restore a previous version.

MATLAB utilizes Git, the free and open source software, to implement its source control features

(http://git-scm.com). The Git system consists of two repositories that store your software versions and

a collection of ways to interact with them. There is a “local” repository that is close to your code folder

(your working folder) in the directory tree. It contains full information about the software versions that

you create. You will interact more often with the local repository. There is also a “remote” repository

that may be more distant from your code folder. It is often on a network or the internet. The remote

repository is essential for synchronizing your work with others. It also can serve as a backup.

Git was developed as a command line program, and it is often used that way. The MATLAB

implementation does not use the command line at all. It operates through right click context menus and

associated windows. The menu items that you will use will always be submenus of the Source Control

menu item.

Git vs.

Subversion

2

Setting up your Git source control To set up Git in MATLAB, you need to

1. Enable Git

2. Create or select a “remote”1 repository

3. Create a local repository

To enable Git, first be sure that source control is enabled in your MATLAB Preferences.

Create your working folder if you don’t have one. This is where your software, documents and other

working files will be created, edited, and worked on.

To create the “remote” repository, first create or identify the folder that will hold it. In this example, the

folder will be named “Git_repo” and exist on your computer in the root C: directory. (The term repo is a

common Git shorthand for repository.) In actual use, this folder might be on a network or the internet.

You will create the remote repository in this folder while creating the local repository in your working

folder.

1 Users often set up the remote repository at a remote location such as a file server or cloud storage to allow for

collaborative file sharing or data backup purposes. The “remote” repository can instead be located on another

disk on your machine, or even on the same disk as the local repository if you wish.

Note: You may

initially set up both

repositories at the

same time.

3

Navigate in MATLAB so that your working folder is the current folder. Right click in an empty area of the

MATLAB Current Folder window, select Source Control and Manage Files in the context menu.

In the Manage Files Using Source Control window, select Git in the Source Control Integration pull down

menu. Note that the working folder appears as the sandbox. (Sandbox is a common term in source

control systems for your working folder.)

Click the Change button for the remote Repository path.

4

In the Select a Repository window, click the plus (+) sign to specify the path to the new remote

repository.

Select the Git_repo folder and click Open.

Click the Validate button in the Select a Repository window. This should produce the valid path message.

Click OK in the Select a Repository window.

5

Click Retrieve in the Manage Files Using Source Control window.

This will create a .git folder in the working folder, which you can see in the MATLAB Current Folder

window. This .git folder is the local repository. Git manages this folder, and you will probably never need

to view or change its contents directly. Note that a Git column has been added to the Current Folder

window.

This sequence of actions also creates the remote repository in the Git_repo folder. In this example, both

repositories are created at the same time.

6

The MATLAB implementation of Git requires that you create a remote repository. You do not need to do

anything with it unless you want to collaborate or have a remote backup.

Putting files into Git source control Git manages (archives and tracks) multiple versions of the files that are in a folder that is under source

control. The basic steps to put a file under source control are:

Step 1: Save the file in the working folder.

Step 2: Add the file to the staging area. (Git takes a snapshot of the file.)

Step 3: Commit the file to the local repository.

The “staging area” is a feature unique to Git. It is not a directory of files but a file that contains

information about what will go into your next commit.

7

For an example of putting a file under source control, write a function in the MATLAB Editor.

After you save the file, there will be an open circle in the Git column beside the file name. This indicates

that the file is not under source control.

If you do not see the open circle, refresh Git status using the right click context menu.

8

Use the right click context menu for this file in the Current Folder window to add it to Git.

This adds the file to the Git staging area, and the symbol in the Git column changes to +. Git has taken a

snapshot of the file.

9

Next commit the file to the local repository using its right click context menu in the Current Folder

window. Sometimes you can right click the file. Other times you will need to right click in an empty part

of the Current Folder window.

It is good practice to include a comment when you commit. Typically this comment would describe or

refer to what has changed since the previous version.

10

After the commit, the symbol in the Git column changes to a green disc.

To put additional files under source control, follow the same sequence: Save the file. Add it to the

staging area. Commit it.

If you have a subfolder under a folder that has a local repository, files in the

subfolder are eligible for source control. You can use the same right click

menu commands. Git will use the same local repository for these files.

This image shows an example subfolder. Note that it has a Git column in its Current Folder window.

If you want to put another folder under source control that is not a subfolder of your working folder,

you will need to create a local repository in the other folder, but you can share the same remote

repository, i.e., they both can point to the same remote repository.

Subfolders

11

Working with revisions You can display revision information for a file using the Show Revisions item in its right click context

menu in the Current Folder window.

which displays the following information for the versions that you have committed.

Note that the file does not need to be selected (or even open) in the Editor to list revisions.

12

When you save a modified version of a file that is already under Git control, a blue square appears in the

Git column.

Git column symbols The MATLAB implementation of Git uses several symbols in the Git column of the Current Folder

window to display the status of a file.

An open circle means that the file is eligible for source control.

A plus sign means that the file has been staged.

A green disc means that the file has been committed.

A blue square means that the file has been modified (in the editor) after it was committed.

13

You can use the right click menu of a modified file to compare changes with or revert to a previous

version.

Interestingly you cannot stage or commit from this menu. You need to right click elsewhere in the folder

window. Then the menu allows you to commit directly—no staging is required for a revision in this

MATLAB implementation if the file has already been committed at least once!

14

This is a feature of the MATLAB implementation. It is not default Git behavior.

After commit, the Git column symbol is updated to the green disc.

You can display revision information using the file’s right click context menu as before.

15

You can compare the details of the two versions using the right click menu for the file.

Then select the version to compare.

16

This opens the MATLAB Comparison window.

As a style point, note that it is much easier to compare versions when you write short lines of code.

You can revert the code to a previous version using the file right click menu.

17

Select the desired version to revert to.

You may need to refresh the file in the Editor to see the reverted file. Note that the symbol in the Git

column has changed to modified.

Using the remote repository If you work alone and do not want a backup to another storage area, you do not need to use the remote

repository.

The remote repository provides a way for more than one programmer to work together. It can also

provide a measure of backup.

18

The Git push and fetch commands transfer files and information between the local and remote

repositories. These commands will not provide any feedback unless there are merge issues.

Additional features In this example, you commit one file at a time. You can also commit all the files in the staging area by

right clicking in a blank part of the Current Folder window.

The commit operation uses the file versions in the staging area, not in the working folder. If a file is

changed after staging but before commit, those changes are not committed.

Git is designed for text files, and you can use it for any text files, not just m files. You can also use Git for

binary files, but you will need to take precautions using a gitattributes file as described in the MATLAB

documentation.

If you decide to put another working folder (not subfolder) under source control, you will create a new

local repository, but you can use the same remote repository. You do not need a different remote

repository for each local repository.

Best practices In general, commit only working code. Specifically, run the test files before committing production code.

If you are working with others or need to sync more than one computer, it is best to have only one

project per remote repository.

Checkout Other source control systems usually have a checkout command that you use to retrieve the most

recently committed version of a file. Git does not have a checkout command. In MATLAB Git, the file

version in your working folder is the current version, provided that it has a green dot in the Git column.

If it does not, you can either work with the version you have or revert to a previous version from your

local repository.

References The MATLAB documentation for Git is helpful after you have used Git for a while.

The official Git documentation is available online.