MATLAB® @ Work
[email protected] 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.
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.
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.)
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.
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.
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.
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.
8 Use the right click context menu for this file in the Current Folder window to add it to Git.
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.
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.
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.
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.
13 You can use the right click menu of a modified file to compare changes with or revert to a previous version.
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.
15 You can compare the details of the two versions using the right click menu for the file.
16 This opens the MATLAB Comparison window.
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.
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.
