Git™ integration with MATLAB® provides distributed source control with support for creating and merging branches. Git is a distributed source control tool, so you can commit changes to a local repository and later synchronize with other remote repositories.
Git supports distributed development because every sandbox contains a complete repository. The full revision history of every file is saved locally. This enables working offline, because you do not need to contact remote repositories for every local edit and commit, only when pushing batches of changes. In addition, you can create your own branches and commit local edits. Doing so is fast, and you do not need to merge with other changes on each commit.
Capabilities of Git source control:
Branch management
Local full revision history
Local access that is quicker than remote access
Offline working
Tracking of file names and contents separately
Enforcing of change logs for tracing accountability
Integration of batches of changes when ready
These capabilities do not suit every situation. If your project is not appropriate for offline working or your repository is too large for a full local revision history, for example, Git is not the ideal source control. In addition, if you need to enforce locking of files before editing, Git does not have this ability. In that situation, SVN is the better choice.
When you use Git in MATLAB, you can:
Create local Git repositories.
Pull and fetch files from remote Git repositories.
Create and switch branches.
Merge branches locally.
Commit locally.
Push files to remote Git repositories.
This diagram represents the distributed Git workflow.
If you want to use Git to merge branches in MATLAB, you must also install a command-line Git client that is available systemwide. You can use other Git functionality without any additional installation.
Some clients are not available systemwide, including the
mingw32
environment provided by GitHub® (Git Shell on the
Start menu). Installing command-line Git makes it available systemwide, and then MATLAB can locate standard ssh
keys.
Check if Git is available by using the command !git
in
MATLAB. If Git is not available, install it. After you have installed a command-line
Git client and registered your files as binary, you can use the merging
features of Git in MATLAB.
On Windows®:
Download the Git installer and run it. You can find command-line Git at:
In the section on adjusting your PATH
, choose the
install option to Use Git from the Windows Command
Prompt. This option adds Git to your PATH
variable, so that
MATLAB can communicate with Git.
In the section on configuring the line-ending conversions, choose the option Checkout as-is, commit as-is to avoid converting any line endings in files.
To avoid corrupting binary files, before using Git to merge branches, register the binary files.
On Linux®, Git is available for most distributions. Install Git for your distribution. For example, on Debian®, install Git by entering:
sudo apt-get install git
On Mac, on Mavericks (10.9) or above, try to run git
from the Terminal. If you do not have Git installed already, it will prompt you to install Xcode Command Line
Tools. For more options, see https://git-scm.com/doc
.
If you use third-party source control tools, you must register your MATLAB and Simulink® file extensions such as .mlx
, .mat
,
.fig
, .mlapp
, .mdl
,
.slx
, .mdlp
, .slxp
,
.sldd
, and .p
as binary formats. If you do not
register the extensions, these tools can corrupt your files when you submit them by changing
end-of-line characters, expanding tokens, substituting keywords, or attempting to automerge.
Corruption can occur whether you use the source control tools outside of MATLAB or if you try submitting files from MATLAB without first registering your file formats.
Also check that other file extensions are registered as binary to avoid corruption at
check-in. Check and register files such as MEX-files, .xlsx
,
.jpg
, .pdf
, .docx
, etc.
After you install a command-line Git client, you can prevent Git from corrupting your files by inserting conflict markers. To do so,
edit your .gitattributes
file to register binary files. For
details, see:
If you do not already have a .gitattributes
file in
your sandbox folder, create one at the MATLAB command prompt:
edit .gitattributes
Add these lines to the .gitattributes
file:
*.mlx -crlf -diff -merge *.mat -crlf -diff -merge *.fig -crlf -diff -merge *.mdl -crlf -diff -merge *.slx -crlf -diff -merge *.mlapp -crlf -diff -merge *.p -crlf -diff -merge *.mdlp -crlf -diff -merge *.slxp -crlf -diff -merge *.sldd -crlf -diff -merge *.slxc -crlf -diff -merge *.mlproj -crlf -diff -merge *.mldatx -crlf -diff -merge *.slreqx -crlf -diff -merge *.sfx -crlf -diff -merge *.sltx -crlf -diff -merge
Check for other file types you use that you also need to register as
binary to avoid corruption at check-in. Check for files such as MEX-files
(.mexa64
, .mexmaci64
,
.mexw64
), .xlsx
,
.jpg
, .pdf
,
.docx
, etc. Add a line to the attributes file for
each file type you need.
Examples:
*.mexa64 -crlf -diff -merge *.mexw64 -crlf -diff -merge *.mexmaci64 -crlf -diff -merge *.xlsx -crlf -diff -merge *.docx -crlf -diff -merge *.pdf -crlf -diff -merge *.jpg -crlf -diff -merge *.png -crlf -diff -merge
Restart MATLAB so you can start using the Git client.
You can reduce your Git repository size by saving Simulink models without compression. Turning off compression results in larger SLX files on disk but reduces repository size.
To use this setting with new SLX files, create your models using a model template with SLX Compression set to none. For existing SLX files, set compression and then save the model. For more information, see Set SLX Compression Level (Simulink).
To reuse code from another repository, you can specify Git submodules.
To clone an external Git repository as a submodule:
Right-click in the MATLAB Current Folder browser, and select Source Control > Submodules.
In the Submodules dialog box, click the + button.
In the Add Submodule dialog box, in the Remote box, specify a repository location. Optionally, click Validate.
In the Path box, specify a location for the submodule and click OK. The Submodules dialog box displays the status and details of the submodule.
Check the status message, and click Close.
After using Pull to get the latest changes from a remote repository, check that submodules are up to date by clicking Submodules and then click Update. If any submodule definition have changed, then the update ensures that the submodule folder contains the correct files. Update applies to all child submodules in the submodule hierarchy.
When you want to manage the added submodule, open the Submodules dialog box.
To get the latest version of a submodule, in the Submodules dialog box, click Fetch.
After fetching, you must merge. Check the
Status message in the Submodules dialog box
for information about your current branch relative to the remote
tracking branch in the repository. When you see the message Behind
, you need to merge in
changes from the repository to your local branch.
Click Branches and merge in the origin changes to your local branch using the Branches dialog box. See Fetch and Merge.
If you make changes in your submodule and want to send changes back to the repository:
Perform a local commit in the parent folder.
Open the Submodules dialog box and click Push.
If you want other users to obtain your changes in the submodule when they clone the parent folder, make sure the index and head match.
In the Submodules dialog box, check the index and head values. The index points to the head commit at the time you first cloned the submodule, or when you last committed the parent folder. If the index and head do not match, you must update the index.
To update the index, commit your changes in the parent folder, and then click Push in the Submodules dialog box. This action makes the index and head the same.