Automatically Merge Models Locally and in CI Pipeline - MATLAB & Simulink (original) (raw)

Main Content

You can enable MATLAB® Git™ integration to automatically merge branches in your Git repository using the mlAutoMerge Git plugin. The plugin can automatically merge branches that contain changes in different subsystems, Stateflow® charts, and configuration sets in the same SLX or MDL file.

Tip

The mlAutoMerge Git plugin automatically merges your model files and resolves conflicts when you are working in different subsystems.

If you are not working in different subsystems, you must merge and resolve conflicts manually. For more information, see Resolve Conflicts in Models Using Three-Way Merge.

Model open in the Simulink Editor on the right and illustration of the merge conflict that corresponds to different blocks in the model on the left

The mlAutoMerge Git plugin automatically merges changes in a child subsystem of a modified subsystem. If the number of ports remains unchanged, child subsystems are independent of parent subsystems. The plugin does not report a conflict for nonfunctional changes such as window positions, open Editor tabs, and other graphical details.

To enable automerge for models in your Git repository:

  1. Run this command in MATLAB.
    comparisons.ExternalSCMLink.setupGitConfig();
    This command automatically populates the global.gitconfig file. An example follows.
    [difftool "mlDiff"]
    cmd = "C:/Program Files/MATLAB/R2024b/bin/win64/mlDiff.bat" LOCALLOCAL LOCALREMOTE
    [mergetool "mlMerge"]
    cmd = "C:/Program Files/MATLAB/R2024b/bin/win64/mlMerge.bat" BASEBASE BASELOCAL REMOTEREMOTE REMOTEMERGED
    [merge "mlAutoMerge"]
    driver = "C:/Program Files/MATLAB/R2024b/bin/win64/mlAutoMerge.bat" %O %A %B %A
    Note
    On a Windows® system, running mlAutoMerge.bat requires a shell to be installed. Git command-line installation by default includes Git bash that provides shell utilities. Make surePath to Shell in the source control Settings is set correctly. For more information, see andConfigure Git Settings.
  2. Configure your Git repository to use the mlAutoMerge executable file for resolving conflicted SLX and MDL files on branch merges. Open the .gitattributes file in your repository and add:
    *.slx binary merge=mlAutoMerge
    *.mdl binary merge=mlAutoMerge
    You can also enable automerge for other file types.
    Supported automerge file types

Now, when you merge branches that contain changes in non-overlapping parts of the same SLX or MDL file, the mlAutoMerge handles the merge automatically.

You can also customize external source control tools to use the MATLAB Comparison Tools and automerge functionality. For more details, see Customize External Source Control to Use MATLAB for Diff and Merge.

This example shows how to enable automerge for Simulink® models using GitLab® CI/CD.

Prerequisites

  1. Open the example to download the attemptAutomerge.sh script and the YAML file .gitlab-ci.yml.
  2. You must configure your repository to use mlAutomerge. Your repository must have a .gitattributes file with the following line: *.slx binary merge=mlAutoMerge
  3. The job, defined in .gitlab-ci.yml, uses a Windows® self-hosted runner configured to use the shell executor. Using a self-hosted runner enables you to customize hardware. To add a self-hosted runner to your repository, follow the instructions at https://docs.gitlab.com/ee/tutorials/create_register_first_runner/#create-and-register-a-project-runner.
  4. Ensure that you have MATLAB and Simulink installed on the self-hosted runner you are using.

Alternatively, if you prefer to use a GitLab-hosted runner, update the .matlab_defaults block in the provided .gitlab-ci.yml file. GitLab-hosted runners implement a MATLAB Container on Docker Hub to run your build using MATLAB R2020b or a later release. For more information, see https://github.com/mathworks/matlab-gitlab-ci-template?tab=readme-ov-file#use-matlab-with-gitlab-cicd.

You can modify the example scripts to work for your own setup depending on the platform and shell your runner uses.

Automerge Simulink Models Using GitLab CI/CD

GitLab CI/CD allows you to automate workflows that you define in YAML files. This example .gitlab-ci.yml attempts to automerge Simulink models for every merge requests to the main branch on GitLab.

To set up the pipeline on GitLab, add the attemptAutomerge.sh and the .gitlab-ci.yml files to your repository by selecting + > Upload file. Then, clone the repository to create a new copy. Alternatively, add the files to your repository in MATLAB and push your changes to the remote repository.

Now, when you create a merge request to merge a development branch with main, it triggers the pipeline you set up and attempts to automerge Simulink models.

Gif showing merge request with conflicts getting cleared by automerge

You can also check the job log for information about the automerge results and status.

Auto-merging models/f14_airframe.slx Merge made by the 'ort' strategy. models/f14_airframe.slx | Bin 48551 -> 48588 bytes 1 file changed, 0 insertions(+), 0 deletions(-)

merge: models/f14_airframe.slx - automerge not supported Unable to automerge models. Conflicts must be resolved locally using the Three-Way Merge tool.

You can also configure your pipeline to attach Simulink model comparison reports to merge requests. For an example .gitlab-ci.yml, see Attach Model Comparison Report to GitLab Merge Requests.

Notes

See Also

Three-Way Merge Tool

Topics