Work. MATLAB Source Control Using Git

Transcription

1 Work 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. Git vs. Subversion 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 ( 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. [email protected] 1

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 Note: You may initially set up both repositories at the same time. 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. 2

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. 3

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. 4

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. 5

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. 6

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. 7

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. 8

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. 9

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. Subfolders 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. 10

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. 11

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. 12

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! 13

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. 14

15 You can compare the details of the two versions using the right click menu for the file. Then select the version to compare. 15

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. 16

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. 17

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. 18