How to best use Git with AIMMS and resolving merge conflicts

I got a question from a client about how to best use Git with AIMMS and how to resolve merge conflicts.

This is what I came up with.

I can provide some general recommendations:

• Make sure you are committing only relevant files 

• • .aimmspacks are binary compiled versions for instance that do not need to be committed

  • /backup /log /PROTemp are also normally not needed in the repository - /data is also normally not committed, unless you like to provide base cases for testing for instance

  • This can help ensure that only git friendly files are committed and handled

• You can use a .gitignore to exclude generated and temporary AIMMS files

Working practices to reduce merge conflicts

• Use multiple files for the source code

• • This can be done in multiple ways. 

  • For instance, you can have local libraries (which have their own folder and .ams files). You can also assign a source code file for any section or module in your project.
    This effectively isolates any code within that section, module or library to a separate source code file. The advantage of this is that, if done in significant/functional ways, people may be working on the same project at the same time, but not changing the same source code file.
    We see many customers adopt this strategy - such as having a GUI, Math Model, Integration and Data processing library.
    https://documentation.aimms.com/language-reference/advanced-language-components/model-structure-and-modules/module-declaration-and-attributes.html
    This also allows you to reutilize libraries in multiple projects.

  • This can also be applied to the webui.json which is more prone to merge conflicts.
    For these case, we also recommend using libraries to separate the pages into libraries with their own JSON files. You can find more on this here: https://documentation.aimms.com/webui/pages-in-library-support.html

• Avoid moving identifiers, sections and declarations - this can generate a larger amount of source code change that is more challenging for GIT to deal with.

• Prefer small, focused branches and “atomic” commits that touch a limited part of the model, instead of large changes spread across many modules and procedures. This makes conflicts both less frequent and easier to understand.

• Align on a simple branching strategy (for example, a main branch for production and short‑lived feature branches) and regularly synchronize branches (rebase or merge frequently) so that parallel work does not diverge too much.

When handling conflicts in AIMMS, they will typically appear in:

• Model source files (.ams) - where unbalanced brackets or braces can occur after manual conflict resolution.

• The name change file .nch, which tracks identifier renames and can also conflict when branches rename or move items differently.

• • This can impact your old .data files - but if you don't use them, it shouldn't be a huge issue.
    In the below link you can find some tips, such as using the "*.nch merge=union" in your .gitattribute - which is a very reasonable solution for this

  • https://community.aimms.com/aimms-language-12/nch-namechange-file-and-version-control-554

Following the above recommendations should already reduce a lot of your conflict.

When resolving conflicts:

• AMS files are structured similar to a JSON file - so resolving conflict with the support of JSON based tools can be helpful

• Using typical GIT tools is also very helpful. I know of two tools used by colleagues at AIMMS - sourcetree and tortoiseGIT.

• • A merge tool that clearly shows “base / current / incoming” versions and allowing your to pay special attention to opening and closing brackets, braces and if/endif blocks. 

  • After resolving a conflict, it is recommended to reopen the project in AIMMS and let the compiler run so that any remaining syntax issues are detected immediately.

• As mentioned above, for .nch conflicts, it is often safer to choose one side as authoritative (e.g., the branch that contains the most recent intended renames) and then re‑apply any missing renames manually in AIMMS, instead of trying to manually merge every conflicting section. Using the union option is also normally safe.​

Additional safeguards

• Consider adopting a code‑review flow with pull requests on GitHub, GitLab, etc. so that another team member can inspect AIMMS changes (especially in large procedures or model sections) before they are merged into your main branch.

• Optionally, you can introduce a simple automated check in your CI pipeline that opens the project in batch mode and compiles it (or runs a small test procedure) after each merge, failing the build if syntax errors remain. This creates a safety net for issues like unclosed brackets.

Do you have any additional tips/tricks/guides or ideas?