MATLAB Community

MATLAB, community & more

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

MATLAB and Git 7

Posted by Ned Gulley,

This week we hear from Toshi Takeuchi about how to take advantage of MATLAB’s recent improvements to Git integration. Toshi is a Senior Marketing Manager at MathWorks.

Quick Introduction to Git with MATLAB

by Toshi Takeuchi

One of the new R2014b features that deserves your attention is Git integration. Git is a source control system (also known as version control or source code management system) that enables collaborative software development. Why does that matter to you? Programming is an essential skill in many technical fields even outside computer science, and some universities now offer software carpentry workshops to enhance coding skills for researchers. Source control is one of those essential skills in software carpentry.

Until now, you may have tinkered alone with code you needed for your project. However, there are other people who may be working on similar problems and they may be writing similar programs. Source control enables you to work with other people so that you don’t have to do it all alone. Collaboration lets you be more productive in other aspects of your project.

Even if you don’t care about such collaboration, wouldn’t it be cool to share your personal project and see other people using it? They may even fix bugs and improve your code for you!

GitHub is one of the most popular websites that host Git repositories. The best place to share your MATLAB projects is File Exchange because of its popularity with the MATLAB user community. And guess what – File Exchange is integrated with GitHub! Now you see the connection?

Basic terminology

What is a Git repository? A repo (repository) is a directory that holds your source code and any associated files. Local repos are on your local drive, and the remote repos are on GitHub or other hosts, and you sync the local repos to remote repos as you write your code. You can start with either the local or remote repos, but in this example I am going to start with a remote repo.

The process looks like this for a single developer:

  1. Create or fork a repo on GitHub
  2. Clone the repo to your local drive – this is your local repo
  3. Add your files to the local repo
  4. Sync your local repo to remote repo
  5. Repeat this process to keep your source code in sync as you write more code
  6. Share your GitHub repo on File Exchange

What is forking?

When you talk about Git, you cannot go without mentioning “forking”. In the simplest terms forking means copying someone else’s public repo on the remote server, rather than starting a repo from scratch. In practice forking is used as a way to contribute to the existing projects or to start a new project using an existing project as a starting point. Once you make changes to your forked project, you can send a merge request to the original developer, and your changes may be accepted and incorporated into the main project.

Forking enables a flexible distributed style of collaboration and number of forks you have on your project acts as a measure of popularity – similar to the count of likes or followers on Facebook or Twitter. The social aspect of forking is an interesting topic on its own, but we need to skip it for this post.

forkRepo

Getting ready

Signing up with GitHub is easy – just click the sign up button on the homepage and follow instructions. A free account would do for now. You also need to download and install Git. Even though GitHub has GUI apps for Windows and Mac, you need to set up the command-line tool for use with MATLAB. You also want to follow these instructions for registering binary files with Git.

Creating a repo

Creating a repo on GitHub is very easy – just follow these instructions. From this point on I will assume you named your repo Hello-World and initialized it with a README file. Please note that you can only create a public repo with a free account.

Cloning the repo to your local drive with MATLAB

Until recently, you needed to use the command line tool for this step, but starting with R2014b we can just use MATLAB’s Current Folder window. No more Git commands like git init, git status, git add, or git commit!

Open your copy of MATLAB and create an empty folder. Right-clicking the empty space in the Current Folder window to bring up a contextual menu, and select Source Control > Manage Files.

managefiles

This will open a new dialog box: Manage Files Using Source Control.

retrieveRepo

  1. For Select control integration, choose Git
  2. For Repository path, click Change

You now see a new dialog box: Select a Repository. Copy and paste the URL of the remote repo you just created. You can find the URL in the right sidebar of your new repo on GitHub.

url

You choose either SSH or HTTPS depending on how you setup your authentication on GitHub.

validateRepo

Click Validate. You may be asked for your login password for authentication. You can close the dialog box when your path is validated.

Back in Manage Files dialog box, the sandbox should be already set to your current folder. All you need to do now is hit Retrieve.

You have now successfully cloned the remote repo to your local drive. Check your Current Folder window. You should see just one file – README.md, but with a green circle next to it. This is just a text file but you can apply wiki-like syntax called markdown to make it appear like a regular web page when viewed on GitHub. README serves as the front page of your repo on GitHub.

currentFolder

Adding files to your local repo

Let’s add a new MATLAB script file helloworld.m. It will appear with a blank circle – it means it is not added to Git source control yet. To add it to Git, right-click on the file and select Add to Git. The empty circle changes to “+” symbol. When you modify a file already under source control, the symbol becomes a blue square.

helloworld

Taking a snapshot with commit

You can continue editing files as you like, but at some point, you want to take a snapshot of the edits you made. That’s when you do a commit. You can select any empty space in the Current Folder window to bring up the contextual menu and select Commit to Git Repository. This will bring up a dialog box where you can add your comment about the changes you made since the last commit. Comments will be helpful to keep to track of your changes and revert back to earlier commits if necessary.

commit

Synching your local repo to remote repo

When you commit, the snapshot is saved in the local repo, but it is also a good idea to mirror the changes to the remote repo as well. To do so, bring up the contextual menu by right-clicking an empty space in the Current Folder window and select Push. That will push your changes to the remote repo. You may need to enter your password.

Branching and Merging

The real power of source control comes from the ability to create multiple branches from your project. By default, you have a branch called “master” in your repo. You can create a new branch from the master branch, makes changes, and then merge those changes back to the master. This mechanism is used for working on new experimental features without affecting the working code on the master. You can branch and merge in MATLAB but the details are beyond the scope of this post.

branching

Closing

If you have been curious about Git but put off by its complicated command line interface, Git integration in R2014b makes Git much more pleasant and approachable. I hope this quick introduction motivates you to take advantage of this new feature. When you do, please don’t forget to post your project to the File Exchange. To learn more about Git, it is actually helpful to start with reviewing the underlying concept about how Git works.

Note

Comments are closed.

7 CommentsOldest to Newest

Royi replied on : 1 of 7
Hi, Could you show an example of 2 people working on the same project and then a Merging should be done? Specifically the case where we both changed the same file and using a text comparison tool to merge the files. A question, could I use my own comparison tool (I really like BeyondCompare)? Thank You for this great post!
Toshi Takeuchi replied on : 2 of 7
Hi Royi, thanks for your feedback. To be perfectly honest, I have not used GitHub for a group project - I am only familiar with a single developer workflow, because I am simply using it as a backup and storage for non-work related code I write personally for fun. For code comparison, I think Git does a very good job, but I cannot comment how well it does relative to BeyondCompare, as I am not familiar with the tool. Take a look at this example - someone out of nowhere sent me a merge request to fix my typos in README on one of my repos, and you can see where this person edited. Of course I gladly accepted his request. :) https://github.com/toshiakit/NaiveBayes/commit/dbe4e57a87c310522e2caaed46596d5e5b44ecf1#diff-04c6e90faac2675aa89e2176d2eec7d8
Royi replied on : 3 of 7
Hi Toshi, I meant how do you initiate the merging process form MATLAB? MATLAB itself has a comparison tool, could you show how to initiate it using MATLAB in the context of GIT support in MATLAB? Thank You.
Dan replied on : 4 of 7
I can't get the initial retrieve to work on my Mac. I know the repository path (a local https address) is valid because SourceTree and the command line version of git accept it. When I click the "Retrieve button", the sandbox directory is created but no files are copied to this directory. An error dialog says "Method not implemented".
Dan replied on : 5 of 7
Update on my previous message: I can get git to work inside MATLAB using ssh but not https. I think this is due to a problem in the libcurl shipped with the Mac version of MATLAB. https://www.mathworks.com/matlabcentral/fileexchange/29154-a-thin-matlab-wrapper-for-the-git-source-control-system
Adrian replied on : 6 of 7
As far as I can see, either the procedure is different, or Git integration doesn't work with OSX (Matlab 2014b, OSX 10.9). Is this right? In order for the "Source Control" entry to appear in the contextual menu one has to set "Other" in the "Source Control" preferences panel (there is no Git option in the drop down menu). Once this is done, "Source Control" appears in the contextual menu, but there is no "Manage Files" option. Any attempt to proceed further produces an error about a customverctrl not being set. Unless I'm missing something basic here.
Toshi Takeuchi replied on : 7 of 7
Hi Dan and Adrian, the new R2014b Git support works fine on my Mac running Mavericks OS 10.9, using the steps outlined above and a https clone URL because that’s how I set up my Github authentication on my Mac (using Keychain). You may have set it up to use SSH. You can only do one or the other. Just in case, I tested again with https://github.com/slayton/matlab-xkcdify/ to make sure (it still works under the new Graphics system!). It wasn't clear to me whether Dan was using R2014b feature or the File Exchange submission he linked to. If you are using the File Exchange submission, then you need to contact the author for your questions. Hope this helps. Adrian, I am not sure what you mean by having to set "Source Control" to "Other" - are you talking about a dialog box you open via "Preferences > General > Source Control"? You should see "Enable MathWorks Source Control Integration" pre-selected. There is nothing you need to do there, as long as you installed Git command line tool. Royi, for branching and merging, the best place to start is the documentation I linked above. I am pasting it here again. https://www.mathworks.com/help/matlab/matlab_prog/branch-and-merge-with-git.html You can also read about the comparison tool here https://www.mathworks.com/help/matlab/matlab_prog/review-changes-in-source-control.html – I haven’t used it very much yet, but it opens a window like this. https://www.mathworks.com/help/matlab/matlab_env/filecompare.png – looks pretty close to what I see on GitHub.