Post on 02-Jan-2017
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.