From 2ef30485279f6d68972b984b489b0969ec8f3eeb Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 16 Jan 2026 17:20:29 +0100 Subject: [PATCH 1/7] VC reorganization --- .../docs/refguide/version-control/_index.md | 133 ++++------------- .../version-control/version-control-faq.md | 141 ++++++++++++++---- 2 files changed, 139 insertions(+), 135 deletions(-) diff --git a/content/en/docs/refguide/version-control/_index.md b/content/en/docs/refguide/version-control/_index.md index 85a06788fb4..f6279d62a7f 100644 --- a/content/en/docs/refguide/version-control/_index.md +++ b/content/en/docs/refguide/version-control/_index.md @@ -18,135 +18,54 @@ Version Control allows you to manage your app development in two ways: Version control in Mendix is built on top [Git](https://git-scm.com). The concepts will be familiar to seasoned users of these version control systems (VCS). Mendix simplifies the VCS commands by building them into Studio Pro and the Mendix Portal. -## Concepts {#concepts} +### Mendix Team Server -### Team Server {#team-server} +[Mendix Team Server](/developerportal/repository/team-server/) is the Mendix-hosted environment that stores all Mendix apps. It facilitates versioning your apps by integrating them into a version control system. Mendix Studio Pro integrates with the Team Server allowing you to create and update apps, commit changes, and merge model versions with one click. -[Team Server](/developerportal/repository/team-server/) is where all the committed versions of Mendix apps are stored. If you commit a revision of an app, it is stored on the Team Server. +## Frequently Asked Questions -To commit to the Team Server you will need to have a role in the app which allows you to edit the app. For more information, see the [Team Roles](/developerportal/general/app-roles/#team-roles) section *App Roles*. +### What Version Control System Is Team Server Built On? {#which-team-server} -For more information on the Team Server and technologies involved, see [Version Control FAQ](/refguide/version-control-faq/). +Mendix Team Server is based on proven technology. Initially it was based only on top of Subversion (SVN), also called Team Server SVN. The Team Server only supports storing apps using Git technology, referred to as Team Server Git. -### Repository {#repository} +### How Much Storage Space Is Provided with Team Server? -Within the [Team Server](#team-server) each app is stored in a repository. This repository contains all the [committed revisions](#commit) for the [Branches](#branches) of the app. +Storage space is unlimited for apps connected to a commercial license. 1 GB of free storage is provided for your company account for apps not (yet) connected to a commercial license. -### Revision {#revision} +### What Happens with My Valuable and Confidential Data? -A revision is the version of your app at a moment in time, stored on the [Team Server](#team-server). +Mendix adheres to strict security standards and considers you the sole owner of your data. Only Mendix Cloud Infrastructure Engineers can access data and will only do so for troubleshooting. Your data is backed up for one year, and the backups are retained for one year after app deletion. You can get a backup of your data at any time by using default Git tools, or, if your app was deleted, by filing a [Mendix Support](https://support.mendix.com/) ticket. -Each revision of your app is given a unique alphanumeric identifier which enables you to find it in future. A new revision is created from Studio Pro when the app is committed to the repository. +### Retrieve and Commit + Push Actions Are Getting Slower -### Working Copy {#working-copy} +This may be caused by the way the storage format of Git interacts with the way the Mendix model stores changes, which can accumulate substantial disk space over time. Studio Pro periodically optimizes your repository if [automatic repository optimization](/refguide/preferences-dialog/#optimization) is enabled. -A working copy is the version of your app which is currently being worked on in Studio Pro. There is one working copy for each development line of the app. This model is held locally, on each computer where development work is taking place. +You can run `git gc` in the command line to manually optimize the repository. `git gc` runs a number of housekeeping tasks, but primarily pack files are created. Pack files store just the changes to the files, which reduces the amount of data which needs to be stored. -### Merge {#merge} +## Cloning my Project Takes a Long Time -Merging is the action of taking one [revision](#revision) of an app and applying the differences which have been made in a different revision. See the [Merging Branches](#merging-branches) section for more information. +Cloning or downloading your app consists of several steps. First the required data is downloaded from the server and then a local unpacking process is executed. The duration of the clone process depends on your repository size, internet connection and computer performance. In case cloning is taking a very long time, consider changing the [Clone type](/refguide/clone-type/) or [troubleshoot repository size](/refguide/troubleshoot-repository-size/). -If any of the differences cannot be applied, then there is a [conflict](#conflict). +## Can I Use the Subversion Version of the Team Server? -### Conflict {#conflict} +No, in Mendix 11, we are supporting only Git-versioned apps. You need to migrate your SVN app to Git to use Mendix 11. For more information on how to migrate, see [Migrate to Git](/developerportal/general/migrate-to-git/) in *Apps*. -A conflict occurs when two versions of the app cannot be combined automatically. This happens when the same document has been changed in a Studio Pro working copy and a committed [revision](#revision) and these changes cannot be reconciled. These are some examples: +## Can I Use Third-Party Tools to Connect to the Team Server? {#third-party-tools} -* The properties of a widget are changed in the revision and the working copy but to different settings -* A document is moved or deleted in the revision but has been changed in a different way in the working copy +Yes, as the Team Server is based on a full implementation of Git. You can directly use third-party tools like GitHub Desktop. For more information on how to set this up, see the [External Tools](/refguide/using-version-control-in-studio-pro/#external-tools) section in *Using Version Control in Studio Pro*. -When a conflict occurs, a developer has to intervene to decide how it should be resolved before it can be committed to the Team Server as a new revision. +## Is It Possible to Connect to a Third-Party or On-Premises Version Control Server? -### Pull {#pull} +Yes, it is possible to connect to a third-party Git version control repository, which is often called BYO-GIT (Bring Your Own Git). -Pulling is the action, invoked in Studio Pro, which gets the latest revision of the current [development line](#development-line) from the repository and merges the differences into the current working copy. +For more information about limitations and the supported Git repositories, see the [Introduction](/refguide/on-premises-git/#intro) and [Preparing Your Repository](/refguide/on-premises-git/#preparing-your-repo) sections in *Working with Git On-Premises Version Control Server*. -### Commit/Push {#commit} +## Does Mendix 11 Support Pull Requests and Peer Reviews? -Committing is the action, invoked in Studio Pro, of creating a set of changes and pushing all your changes to the [repository](#repository) and making a new [revision](#revision). It is possible to store the committed data in a local repository, but not yet push it to the central [repository](#repository). +Studio Pro supports peer review and merging through the version control functionalities available in Studio Pro. For more information on how to set this process up, see [Using Version Control in Studio Pro](/refguide/using-version-control-in-studio-pro/). +Currently, Mendix does not support pull or merge requests through the Team Server for Mendix. When using third-party tools it is possible to review the following code extensions: -If there are no conflicts, the changes are then sent to the repository to make a new revision. - -### Development Line {#development-line} - -Development of an app is done in a development line where a set of related changes is made. There are two types of development lines: the [main line](#main-line) and [branch lines](#branch-line). - -#### Main Line {#main-line} - -The main line is the initial development line for the app and is usually kept as the version which will be deployed to the production environment. Simple apps, and apps which do not require a high degree of collaboration, may only have a main line. - -#### Branch Line {#branch-line} - -A branch line is a way of making an independent set of changes which can be tested away from the main line. - -See the [Branches](#branches) section below for more information on how branch lines can be used. - -### Tag {#tag} - -A Tag is a way of identifying a commit in addition to the [revision](#revision) number. It is specified by the developer and has four parts: - -* Major: used to identify significant new functionality, a new user interface, or other important change -* Minor: used to identify new functionality which augments the main function of the app -* Patch: used to identify a fix to an error in a previously-released app -* Revision: this is added automatically and is the revision number of the commit - -### Repository Service - -The Repository Service manages communication between Studio Pro and other supporting services (for example, Team Server). The developer will not generally be aware that they are communicating via the Repository Service. - -### Mendix MPR Storage {#mpr-format} - -An app modeled in Mendix is stored in an *.mpr* file, a database that contains data on all documents, such as microflows, workflows, pages. Studio Pro or the [mx Command-Line Tool](/refguide/mx-command-line-tool/) is required to inspect changes in the *.mpr*. - -{{% alert color="warning" %}} -Manually modifying files belonging to the *.mpr* storage format such as the *.mpr* file or the *mprcontents* directory (for example, when resolving file conflicts through third-party tooling), will lead to a corrupted state. To recover from a corrupted state a previous commit will need to be restored. -{{% /alert %}} -{{% alert color="warning" %}} -Renaming the app by renaming the *.mpr* file is not supported. Renaming your app when using version control is only supported via the Mendix Portal. For more information, see the [Page Header](/developerportal/general-settings/#settings-page-header) section in *Settings*. -{{% /alert %}} - -## Branches {#branches} - -With more complex apps, you may want to manage your code in a more sophisticated way. For example, you may want to develop new features separately from the currently deployed version of your app so that you can fix any bugs without having to release all the new features. This is done using [Branch Lines](#branch-line). - -If you are already familiar with using branches, you can check the [Branching Best-Practices](/refguide/using-version-control-in-studio-pro/#branching-best-practices) section of *Using Version Control in Studio Pro* for advice on how to use branches when developing your Mendix app. - -### Main Line - -All apps are developed along the main line. Here you have all development happening along a single line, with all changes built upon the previous revision: - -{{< figure src="/attachments/refguide/version-control/image7.png" class="no-border" >}} - -### Branch Line - -When you add a branch line, you take a copy of an existing [revision](#revision) and work separately on that copy. Changes made to one branch do not impact any other branches. - -In Mendix each commit within a [repository](#repository) is given a unique identifier. - -{{< figure src="/attachments/refguide/version-control/image8.png" class="no-border" >}} - -### Merging Branches {#merging-branches} - -You may have a branch line which will continue independently and never need to be combined with any other development lines. For example, you may create a branch for a particular release of your app and only ever use it to fix bugs in that release. - -On the other hand, you may want to add the features from one branch line into another development line. These are two cases for doing this: - -* You develop new features in a branch line and want to include them in your main development line -* You want to take advantage of a bug fix which was made on another branch line - -You can merge a specific revision of a branch line into your current [working copy](#working-copy). If, for example, you were working on the main line updated to revision 6, you can [merge](#merge) revision 5 from another branch line into your working copy. Then you can commit the result to create revision 7. If you want to merge several different committed changes from a branch, you will need to select a range of revisions which includes all the changes. - -{{< figure src="/attachments/refguide/version-control/image9.png" class="no-border" >}} - -{{% alert color="info" %}} - -You are expected to merge branch lines into the main line before upgrading to a version that is one or more **major** versions newer than the current one. -It is also highly recommended to either commit or revert all changes before such an upgrade so there are no uncommitted changes during the upgrade. - -{{% /alert %}} - -There may be conflicts during the merge, and these will have to be resolved before you can commit the changes to your app. - -Note that errors can be introduced by the [merge](#merge) process even if no conflicts are identified during the merge. Errors are inconsistencies which are flagged in Studio Pro and will prevent the app from being deployed. They could lead to a revision not being deployable, so it is important to check for errors after you have done a merge. +* code for Java and JavaScript actions +* HTML/CSS for theming ## Documents in This Category diff --git a/content/en/docs/refguide/version-control/version-control-faq.md b/content/en/docs/refguide/version-control/version-control-faq.md index feabffb8ce6..c534205e391 100644 --- a/content/en/docs/refguide/version-control/version-control-faq.md +++ b/content/en/docs/refguide/version-control/version-control-faq.md @@ -1,54 +1,139 @@ --- -title: "Version Control FAQ" -url: /refguide/version-control-faq/ -weight: 30 -description: "Presents and explains several frequently asked questions about version control." +title: "Version Control Glossary" +url: /refguide/version-control-glossary/ +weight: 100 +description: "Presents and explains several concepts related to version control." --- ## Introduction -[Mendix Team Server](/developerportal/repository/team-server/) is the Mendix-hosted environment that stores all Mendix apps. It facilitates versioning your apps by integrating them into a version control system. Mendix Studio Pro integrates with the Team Server allowing you to create and update apps, commit changes, and merge model versions with one click. +## Concepts {#concepts} -## What Version Control System Is Team Server Built On? {#which-team-server} +### Team Server {#team-server} -Mendix Team Server is based on proven technology. Initially it was based only on top of Subversion (SVN), also called Team Server SVN. The Team Server only supports storing apps using Git technology, referred to as Team Server Git. +[Team Server](/developerportal/repository/team-server/) is where all the committed versions of Mendix apps are stored. If you commit a revision of an app, it is stored on the Team Server. -## How Much Storage Space Is Provided with Team Server? +To commit to the Team Server you will need to have a role in the app which allows you to edit the app. For more information, see the [Team Roles](/developerportal/general/app-roles/#team-roles) section *App Roles*. -Storage space is unlimited for apps connected to a commercial license. 1 GB of free storage is provided for your company account for apps not (yet) connected to a commercial license. +For more information on the Team Server and technologies involved, see [Version Control FAQ](/refguide/version-control-faq/). -## What Happens with My Valuable and Confidential Data? +### Repository {#repository} -Mendix adheres to strict security standards and considers you the sole owner of your data. Only Mendix Cloud Infrastructure Engineers can access data and will only do so for troubleshooting. Your data is backed up for one year, and the backups are retained for one year after app deletion. You can get a backup of your data at any time by using default Git tools, or, if your app was deleted, by filing a [Mendix Support](https://support.mendix.com/) ticket. +Within the [Team Server](#team-server) each app is stored in a repository. This repository contains all the [committed revisions](#commit) for the [Branches](#branches) of the app. -## Retrieve and Commit + Push Actions Are Getting Slower +### Revision {#revision} -This may be caused by the way the storage format of Git interacts with the way the Mendix model stores changes, which can accumulate substantial disk space over time. Studio Pro periodically optimizes your repository if [automatic repository optimization](/refguide/preferences-dialog/#optimization) is enabled. +A revision is the version of your app at a moment in time, stored on the [Team Server](#team-server). -You can run `git gc` in the command line to manually optimize the repository. `git gc` runs a number of housekeeping tasks, but primarily pack files are created. Pack files store just the changes to the files, which reduces the amount of data which needs to be stored. +Each revision of your app is given a unique alphanumeric identifier which enables you to find it in future. A new revision is created from Studio Pro when the app is committed to the repository. -## Cloning my Project Takes a Long Time +### Working Copy {#working-copy} -Cloning or downloading your app consists of several steps. First the required data is downloaded from the server and then a local unpacking process is executed. The duration of the clone process depends on your repository size, internet connection and computer performance. In case cloning is taking a very long time, consider changing the [Clone type](/refguide/clone-type/) or [troubleshoot repository size](/refguide/troubleshoot-repository-size/). +A working copy is the version of your app which is currently being worked on in Studio Pro. There is one working copy for each development line of the app. This model is held locally, on each computer where development work is taking place. -## Can I Use the Subversion Version of the Team Server? +### Merge {#merge} -No, in Mendix 11, we are supporting only Git-versioned apps. You need to migrate your SVN app to Git to use Mendix 11. For more information on how to migrate, see [Migrate to Git](/developerportal/general/migrate-to-git/) in *Apps*. +Merging is the action of taking one [revision](#revision) of an app and applying the differences which have been made in a different revision. See the [Merging Branches](#merging-branches) section for more information. -## Can I Use Third-Party Tools to Connect to the Team Server? {#third-party-tools} +If any of the differences cannot be applied, then there is a [conflict](#conflict). -Yes, as the Team Server is based on a full implementation of Git. You can directly use third-party tools like GitHub Desktop. For more information on how to set this up, see the [External Tools](/refguide/using-version-control-in-studio-pro/#external-tools) section in *Using Version Control in Studio Pro*. +### Conflict {#conflict} -## Is It Possible to Connect to a Third-Party or On-Premises Version Control Server? +A conflict occurs when two versions of the app cannot be combined automatically. This happens when the same document has been changed in a Studio Pro working copy and a committed [revision](#revision) and these changes cannot be reconciled. These are some examples: -Yes, it is possible to connect to a third-party Git version control repository, which is often called BYO-GIT (Bring Your Own Git). +* The properties of a widget are changed in the revision and the working copy but to different settings +* A document is moved or deleted in the revision but has been changed in a different way in the working copy -For more information about limitations and the supported Git repositories, see the [Introduction](/refguide/on-premises-git/#intro) and [Preparing Your Repository](/refguide/on-premises-git/#preparing-your-repo) sections in *Working with Git On-Premises Version Control Server*. +When a conflict occurs, a developer has to intervene to decide how it should be resolved before it can be committed to the Team Server as a new revision. -## Does Mendix 11 Support Pull Requests and Peer Reviews? +### Pull {#pull} -Studio Pro supports peer review and merging through the version control functionalities available in Studio Pro. For more information on how to set this process up, see [Using Version Control in Studio Pro](/refguide/using-version-control-in-studio-pro/). -Currently, Mendix does not support pull or merge requests through the Team Server for Mendix. When using third-party tools it is possible to review the following code extensions: +Pulling is the action, invoked in Studio Pro, which gets the latest revision of the current [development line](#development-line) from the repository and merges the differences into the current working copy. -* code for Java and JavaScript actions -* HTML/CSS for theming +### Commit/Push {#commit} + +Committing is the action, invoked in Studio Pro, of creating a set of changes and pushing all your changes to the [repository](#repository) and making a new [revision](#revision). It is possible to store the committed data in a local repository, but not yet push it to the central [repository](#repository). + +If there are no conflicts, the changes are then sent to the repository to make a new revision. + +### Development Line {#development-line} + +Development of an app is done in a development line where a set of related changes is made. There are two types of development lines: the [main line](#main-line) and [branch lines](#branch-line). + +#### Main Line {#main-line} + +The main line is the initial development line for the app and is usually kept as the version which will be deployed to the production environment. Simple apps, and apps which do not require a high degree of collaboration, may only have a main line. + +#### Branch Line {#branch-line} + +A branch line is a way of making an independent set of changes which can be tested away from the main line. + +See the [Branches](#branches) section below for more information on how branch lines can be used. + +### Tag {#tag} + +A Tag is a way of identifying a commit in addition to the [revision](#revision) number. It is specified by the developer and has four parts: + +* Major: used to identify significant new functionality, a new user interface, or other important change +* Minor: used to identify new functionality which augments the main function of the app +* Patch: used to identify a fix to an error in a previously-released app +* Revision: this is added automatically and is the revision number of the commit + +### Repository Service + +The Repository Service manages communication between Studio Pro and other supporting services (for example, Team Server). The developer will not generally be aware that they are communicating via the Repository Service. + +### Mendix MPR Storage {#mpr-format} + +An app modeled in Mendix is stored in an *.mpr* file, a database that contains data on all documents, such as microflows, workflows, pages. Studio Pro or the [mx Command-Line Tool](/refguide/mx-command-line-tool/) is required to inspect changes in the *.mpr*. + +{{% alert color="warning" %}} +Manually modifying files belonging to the *.mpr* storage format such as the *.mpr* file or the *mprcontents* directory (for example, when resolving file conflicts through third-party tooling), will lead to a corrupted state. To recover from a corrupted state a previous commit will need to be restored. +{{% /alert %}} +{{% alert color="warning" %}} +Renaming the app by renaming the *.mpr* file is not supported. Renaming your app when using version control is only supported via the Mendix Portal. For more information, see the [Page Header](/developerportal/general-settings/#settings-page-header) section in *Settings*. +{{% /alert %}} + +## Branches {#branches} + +With more complex apps, you may want to manage your code in a more sophisticated way. For example, you may want to develop new features separately from the currently deployed version of your app so that you can fix any bugs without having to release all the new features. This is done using [Branch Lines](#branch-line). + +If you are already familiar with using branches, you can check the [Branching Best-Practices](/refguide/using-version-control-in-studio-pro/#branching-best-practices) section of *Using Version Control in Studio Pro* for advice on how to use branches when developing your Mendix app. + +### Main Line + +All apps are developed along the main line. Here you have all development happening along a single line, with all changes built upon the previous revision: + +{{< figure src="/attachments/refguide/version-control/image7.png" class="no-border" >}} + +### Branch Line + +When you add a branch line, you take a copy of an existing [revision](#revision) and work separately on that copy. Changes made to one branch do not impact any other branches. + +In Mendix each commit within a [repository](#repository) is given a unique identifier. + +{{< figure src="/attachments/refguide/version-control/image8.png" class="no-border" >}} + +### Merging Branches {#merging-branches} + +You may have a branch line which will continue independently and never need to be combined with any other development lines. For example, you may create a branch for a particular release of your app and only ever use it to fix bugs in that release. + +On the other hand, you may want to add the features from one branch line into another development line. These are two cases for doing this: + +* You develop new features in a branch line and want to include them in your main development line +* You want to take advantage of a bug fix which was made on another branch line + +You can merge a specific revision of a branch line into your current [working copy](#working-copy). If, for example, you were working on the main line updated to revision 6, you can [merge](#merge) revision 5 from another branch line into your working copy. Then you can commit the result to create revision 7. If you want to merge several different committed changes from a branch, you will need to select a range of revisions which includes all the changes. + +{{< figure src="/attachments/refguide/version-control/image9.png" class="no-border" >}} + +{{% alert color="info" %}} + +You are expected to merge branch lines into the main line before upgrading to a version that is one or more **major** versions newer than the current one. +It is also highly recommended to either commit or revert all changes before such an upgrade so there are no uncommitted changes during the upgrade. + +{{% /alert %}} + +There may be conflicts during the merge, and these will have to be resolved before you can commit the changes to your app. + +Note that errors can be introduced by the [merge](#merge) process even if no conflicts are identified during the merge. Errors are inconsistencies which are flagged in Studio Pro and will prevent the app from being deployed. They could lead to a revision not being deployable, so it is important to check for errors after you have done a merge. From a2f4f91dd432ec8f1979dff0960ff5dd0738f70b Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 22 Jan 2026 10:53:35 +0100 Subject: [PATCH 2/7] Reorganizing the TOC --- .../_index.md | 29 +-------------- .../version-control/version-control-enable.md | 37 +++++++++++++++++++ ...rol-faq.md => version-control-glossary.md} | 2 +- .../version-control-troubleshooting/_index.md | 2 +- 4 files changed, 40 insertions(+), 30 deletions(-) create mode 100644 content/en/docs/refguide/version-control/version-control-enable.md rename content/en/docs/refguide/version-control/{version-control-faq.md => version-control-glossary.md} (99%) diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/_index.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/_index.md index 1a9a89901a7..681f9384573 100644 --- a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/_index.md +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/_index.md @@ -2,7 +2,7 @@ title: "Using Version Control in Studio Pro" url: /refguide/using-version-control-in-studio-pro/ linktitle: "Using Version Control" -weight: 10 +weight: 50 description: "Describes how to work with version control and how to resolve some issues which may arise." # Renamed from version-control-scenarios --- @@ -13,33 +13,6 @@ This document describes how to use version control in Mendix Studio Pro. For more information on related concepts and the theory behind how version control works in Mendix, see [Version Control](/refguide/version-control/). -## Starting an App with Version Control - -To start a new app with version control, do the following: - -1. Open Studio Pro. -2. In the **Select App** dialog box, click **Create New App**. -3. Select the starting point – an app template. -4. In the **App Settings** dialog box, make sure that **Enable online services** is set to *Yes*. This option creates a remote (Team Server) repository and an app in [Apps](https://sprintr.home.mendix.com/) of the Mendix Portal. -5. Optionally, change the default **App directory** set by Studio Pro. -6. Click **Create app**. - -The app is created on the Team Server, and a working copy is created in the **App directory**. This is opened in Studio Pro so that you can start working immediately. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/app-settings.png" class="no-border" >}} - -## Joining an App - -If there is already a Team Server-enabled app, you can be invited to join it (see [Team](/developerportal/general/team/)). - -Once you are a team member, provided that you have been given a role with sufficient rights, you can work on the app by doing the following: - -1. Choose **Open App** in Studio Pro. -2. Choose your app from the list of the **Open App** dialog box. -3. Click **Open in Studio Pro**. - -The app will be downloaded from the Team Server and opened in Studio Pro. - ## Day-to-Day Development Let us say you have a working copy of an app on disk. You make changes to the app and save them. Saved changes are not immediately visible to others. The documents, folders, and modules that have been changed can be identified by looking at the **status**. diff --git a/content/en/docs/refguide/version-control/version-control-enable.md b/content/en/docs/refguide/version-control/version-control-enable.md new file mode 100644 index 00000000000..e857d5d3e78 --- /dev/null +++ b/content/en/docs/refguide/version-control/version-control-enable.md @@ -0,0 +1,37 @@ +--- +title: "Enabling Version Control for Your App" +url: /refguide/version-control/enable/ +weight: 10 +description: "Learn how you can start or join an app that uses version control." +--- + +## Introduction {#intro} + +To use version control for your Mendix application, you can either start a new app, or join an existing app with version control already enabled. + +## Starting an App with Version Control + +To start a new app with version control, do the following: + +1. Open Studio Pro. +2. In the **Select App** dialog box, click **Create New App**. +3. Select the starting point – an app template. +4. In the **App Settings** dialog box, make sure that **Enable online services** is set to *Yes*. This option creates a remote (Team Server) repository and an app in [Apps](https://sprintr.home.mendix.com/) of the Mendix Portal. +5. Optionally, change the default **App directory** set by Studio Pro. +6. Click **Create app**. + +The app is created on the Team Server, and a working copy is created in the **App directory**. This is opened in Studio Pro so that you can start working immediately. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/app-settings.png" class="no-border" >}} + +## Joining an App + +If there is already a Team Server-enabled app, you can be invited to join it (see [Team](/developerportal/general/team/)). + +Once you are a team member, provided that you have been given a role with sufficient rights, you can work on the app by doing the following: + +1. Choose **Open App** in Studio Pro. +2. Choose your app from the list of the **Open App** dialog box. +3. Click **Open in Studio Pro**. + +The app will be downloaded from the Team Server and opened in Studio Pro. \ No newline at end of file diff --git a/content/en/docs/refguide/version-control/version-control-faq.md b/content/en/docs/refguide/version-control/version-control-glossary.md similarity index 99% rename from content/en/docs/refguide/version-control/version-control-faq.md rename to content/en/docs/refguide/version-control/version-control-glossary.md index c534205e391..4af9f34a372 100644 --- a/content/en/docs/refguide/version-control/version-control-faq.md +++ b/content/en/docs/refguide/version-control/version-control-glossary.md @@ -1,6 +1,6 @@ --- title: "Version Control Glossary" -url: /refguide/version-control-glossary/ +url: /refguide/version-control/glossary/ weight: 100 description: "Presents and explains several concepts related to version control." --- diff --git a/content/en/docs/refguide/version-control/version-control-troubleshooting/_index.md b/content/en/docs/refguide/version-control/version-control-troubleshooting/_index.md index 8e63017f481..a3a5aac348d 100644 --- a/content/en/docs/refguide/version-control/version-control-troubleshooting/_index.md +++ b/content/en/docs/refguide/version-control/version-control-troubleshooting/_index.md @@ -2,7 +2,7 @@ title: "Troubleshooting Version Control" url: /refguide/troubleshoot-version-control-issues/ linktitle: "Troubleshoot Version Control" -weight: 20 +weight: 90 description: "Presents a list of problems and fixes for version control issues." aliases: - /howto/collaboration-requirements-management/troubleshoot-version-control-issues/ From d3021b831c8f6a9c53adbecfbec022699ceda12b Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 22 Jan 2026 10:57:13 +0100 Subject: [PATCH 3/7] Reorganizing the TOC --- .../refguide/version-control/configure/_index.md | 15 +++++++++++++++ .../{ => configure}/on-premises-git.md | 3 +-- 2 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 content/en/docs/refguide/version-control/configure/_index.md rename content/en/docs/refguide/version-control/{ => configure}/on-premises-git.md (99%) diff --git a/content/en/docs/refguide/version-control/configure/_index.md b/content/en/docs/refguide/version-control/configure/_index.md new file mode 100644 index 00000000000..0a55e701e8d --- /dev/null +++ b/content/en/docs/refguide/version-control/configure/_index.md @@ -0,0 +1,15 @@ +--- +title: "Configuring Version Control" +url: /refguide/uversion-control/configure/ +linktitle: "Using Version Control" +weight: 30 +description: "Describes how to configure version control for your Mendix application." +--- + +## Introduction + +This document describes how to configure version control in Mendix Studio Pro. + +For more information on related concepts and the theory behind how version control works in Mendix, see [Version Control](/refguide/version-control/). + +[TBD] \ No newline at end of file diff --git a/content/en/docs/refguide/version-control/on-premises-git.md b/content/en/docs/refguide/version-control/configure/on-premises-git.md similarity index 99% rename from content/en/docs/refguide/version-control/on-premises-git.md rename to content/en/docs/refguide/version-control/configure/on-premises-git.md index 9d76b15f906..ce96737a7f5 100644 --- a/content/en/docs/refguide/version-control/on-premises-git.md +++ b/content/en/docs/refguide/version-control/configure/on-premises-git.md @@ -1,6 +1,5 @@ --- -title: "Working with Git On-Premises Version Control Server" -linktitle: "Git On-Premises Version Control Server" +title: "Optional: Working with Private Git" url: /refguide/on-premises-git/ weight: 60 description: "Introduces how to work with Git on-premises version control server." From 6dcdc9aaab015ef2bde2cb95fd07efdf797e9d42 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 22 Jan 2026 10:58:48 +0100 Subject: [PATCH 4/7] Reorganizing the TOC --- .../auto-fetch.md | 0 .../clone-type.md | 0 .../git-storage-optimization-dialog.md | 0 .../docs/refguide/version-control/configure/on-premises-git.md | 2 +- 4 files changed, 1 insertion(+), 1 deletion(-) rename content/en/docs/refguide/version-control/{using-version-control-in-studio-pro => configure}/auto-fetch.md (100%) rename content/en/docs/refguide/version-control/{using-version-control-in-studio-pro => configure}/clone-type.md (100%) rename content/en/docs/refguide/version-control/{using-version-control-in-studio-pro => configure}/git-storage-optimization-dialog.md (100%) diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/auto-fetch.md b/content/en/docs/refguide/version-control/configure/auto-fetch.md similarity index 100% rename from content/en/docs/refguide/version-control/using-version-control-in-studio-pro/auto-fetch.md rename to content/en/docs/refguide/version-control/configure/auto-fetch.md diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/clone-type.md b/content/en/docs/refguide/version-control/configure/clone-type.md similarity index 100% rename from content/en/docs/refguide/version-control/using-version-control-in-studio-pro/clone-type.md rename to content/en/docs/refguide/version-control/configure/clone-type.md diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/git-storage-optimization-dialog.md b/content/en/docs/refguide/version-control/configure/git-storage-optimization-dialog.md similarity index 100% rename from content/en/docs/refguide/version-control/using-version-control-in-studio-pro/git-storage-optimization-dialog.md rename to content/en/docs/refguide/version-control/configure/git-storage-optimization-dialog.md diff --git a/content/en/docs/refguide/version-control/configure/on-premises-git.md b/content/en/docs/refguide/version-control/configure/on-premises-git.md index ce96737a7f5..cb99aacdae2 100644 --- a/content/en/docs/refguide/version-control/configure/on-premises-git.md +++ b/content/en/docs/refguide/version-control/configure/on-premises-git.md @@ -1,7 +1,7 @@ --- title: "Optional: Working with Private Git" url: /refguide/on-premises-git/ -weight: 60 +weight: 80 description: "Introduces how to work with Git on-premises version control server." aliases: - /howto/collaboration-requirements-management/on-premises-git-howto/ From 4d1b8db4edc2672b9cd76445d855f3ba8061b5ae Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 22 Jan 2026 17:39:38 +0100 Subject: [PATCH 5/7] SME review --- .../refguide/version-control/version-control-enable.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/content/en/docs/refguide/version-control/version-control-enable.md b/content/en/docs/refguide/version-control/version-control-enable.md index e857d5d3e78..263e9bc5e42 100644 --- a/content/en/docs/refguide/version-control/version-control-enable.md +++ b/content/en/docs/refguide/version-control/version-control-enable.md @@ -7,7 +7,7 @@ description: "Learn how you can start or join an app that uses version control." ## Introduction {#intro} -To use version control for your Mendix application, you can either start a new app, or join an existing app with version control already enabled. +Version control is automatically enabled for every new Mendix application that you create. [TBD] ## Starting an App with Version Control @@ -16,7 +16,7 @@ To start a new app with version control, do the following: 1. Open Studio Pro. 2. In the **Select App** dialog box, click **Create New App**. 3. Select the starting point – an app template. -4. In the **App Settings** dialog box, make sure that **Enable online services** is set to *Yes*. This option creates a remote (Team Server) repository and an app in [Apps](https://sprintr.home.mendix.com/) of the Mendix Portal. +4. In the **App Settings** dialog box, make sure that **Enable online services** is set to **Yes**. This option creates a remote (Team Server) repository and an app in [Apps](https://sprintr.home.mendix.com/) of the Mendix Portal. 5. Optionally, change the default **App directory** set by Studio Pro. 6. Click **Create app**. @@ -34,4 +34,8 @@ Once you are a team member, provided that you have been given a role with suffic 2. Choose your app from the list of the **Open App** dialog box. 3. Click **Open in Studio Pro**. -The app will be downloaded from the Team Server and opened in Studio Pro. \ No newline at end of file +The app will be downloaded from the Team Server and opened in Studio Pro. + +## Enabling Version Control for an Existing App + +[add info: https://docs.mendix.com/refguide/upload-to-version-control-dialog/] \ No newline at end of file From 76fedc3b50e56b7ffcc53485da4a289b60ae3146 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Tue, 10 Feb 2026 12:59:29 +0100 Subject: [PATCH 6/7] draft --- .../menus/file-menu/open-app-dialog.md | 2 +- .../branch-line-manager-dialog/_index.md | 2 +- .../create-branch-line-dialog.md | 2 +- .../docs/refguide/version-control/_index.md | 12 - .../version-control/configure/auto-fetch.md | 2 +- .../version-control/configure/clone-type.md | 2 +- .../git-storage-optimization-dialog.md | 2 +- .../_index.md | 493 +----------------- .../deploy-external.md | 80 +++ .../managing-branches.md | 176 +++++++ .../peer-review.md | 29 ++ .../push-pull.md | 163 ++++++ ...ge-algorithm.md => resolving-conflicts.md} | 11 +- .../reverting-changes.md | 48 ++ .../version-cloud-app.md | 46 ++ .../version-control-troubleshooting/_index.md | 15 +- 16 files changed, 569 insertions(+), 516 deletions(-) create mode 100644 content/en/docs/refguide/version-control/using-version-control-in-studio-pro/deploy-external.md create mode 100644 content/en/docs/refguide/version-control/using-version-control-in-studio-pro/managing-branches.md create mode 100644 content/en/docs/refguide/version-control/using-version-control-in-studio-pro/peer-review.md create mode 100644 content/en/docs/refguide/version-control/using-version-control-in-studio-pro/push-pull.md rename content/en/docs/refguide/version-control/using-version-control-in-studio-pro/{merge-algorithm.md => resolving-conflicts.md} (98%) create mode 100644 content/en/docs/refguide/version-control/using-version-control-in-studio-pro/reverting-changes.md create mode 100644 content/en/docs/refguide/version-control/using-version-control-in-studio-pro/version-cloud-app.md diff --git a/content/en/docs/refguide/modeling/menus/file-menu/open-app-dialog.md b/content/en/docs/refguide/modeling/menus/file-menu/open-app-dialog.md index fc36e121653..4a9ec707699 100644 --- a/content/en/docs/refguide/modeling/menus/file-menu/open-app-dialog.md +++ b/content/en/docs/refguide/modeling/menus/file-menu/open-app-dialog.md @@ -26,7 +26,7 @@ Apps can be located on the Team Server, on another Git server, or on the local d ### Selecting an App {#select-app} -You can select an app from the list of your apps. Once you have selected an app, you can either choose a [branch line](/refguide/version-control/#branches) that you would like to open or click **Open in Studio Pro** and the branch that is indicated in the **Current Branch** column will open: +You can select an app from the list of your apps. Once you have selected an app, you can either choose a [branch line](/refguide/version-control/glossary/#branches) that you would like to open or click **Open in Studio Pro** and the branch that is indicated in the **Current Branch** column will open: {{< figure src="/attachments/refguide/modeling/menus/file-menu/open-app-dialog/select-app.png" class="no-border" width="700" >}} diff --git a/content/en/docs/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/_index.md b/content/en/docs/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/_index.md index 2048c1ee6dc..030afa7dbcb 100644 --- a/content/en/docs/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/_index.md +++ b/content/en/docs/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/_index.md @@ -6,7 +6,7 @@ weight: 80 ## Introduction -The **Branch Line Manager** is used to manage the [branch lines](/refguide/version-control/#branches) of an app that are stored on a version control server. You can create or delete branch lines for your app, and you can change the branch line that you are working on. +The **Branch Line Manager** is used to manage the [branch lines](/refguide/version-control/glossary/#branches) of an app that are stored on a version control server. You can create or delete branch lines for your app, and you can change the branch line that you are working on. To view the **Branch Line Manager** dialog box, open **Version Control** > **Manage Branch Lines**. diff --git a/content/en/docs/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/create-branch-line-dialog.md b/content/en/docs/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/create-branch-line-dialog.md index fc075730ed2..39b4b505f55 100644 --- a/content/en/docs/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/create-branch-line-dialog.md +++ b/content/en/docs/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/create-branch-line-dialog.md @@ -6,7 +6,7 @@ weight: 10 ## Introduction -Use the **Create Branch Line** dialog box to create a new [branch line](/refguide/version-control/#branches) via the **Branch Line Manager**: +Use the **Create Branch Line** dialog box to create a new [branch line](/refguide/version-control/glossary/#branches) via the **Branch Line Manager**: {{< figure src="/attachments/refguide/modeling/menus/version-control-menu/branch-line-manager-dialog/create-branch-line-dialog/create-branch-line.png" class="no-border" width="550" >}} diff --git a/content/en/docs/refguide/version-control/_index.md b/content/en/docs/refguide/version-control/_index.md index f6279d62a7f..55f479886d2 100644 --- a/content/en/docs/refguide/version-control/_index.md +++ b/content/en/docs/refguide/version-control/_index.md @@ -22,8 +22,6 @@ Version control in Mendix is built on top [Git](https://git-scm.com). The concep [Mendix Team Server](/developerportal/repository/team-server/) is the Mendix-hosted environment that stores all Mendix apps. It facilitates versioning your apps by integrating them into a version control system. Mendix Studio Pro integrates with the Team Server allowing you to create and update apps, commit changes, and merge model versions with one click. -## Frequently Asked Questions - ### What Version Control System Is Team Server Built On? {#which-team-server} Mendix Team Server is based on proven technology. Initially it was based only on top of Subversion (SVN), also called Team Server SVN. The Team Server only supports storing apps using Git technology, referred to as Team Server Git. @@ -36,16 +34,6 @@ Storage space is unlimited for apps connected to a commercial license. 1 GB of f Mendix adheres to strict security standards and considers you the sole owner of your data. Only Mendix Cloud Infrastructure Engineers can access data and will only do so for troubleshooting. Your data is backed up for one year, and the backups are retained for one year after app deletion. You can get a backup of your data at any time by using default Git tools, or, if your app was deleted, by filing a [Mendix Support](https://support.mendix.com/) ticket. -### Retrieve and Commit + Push Actions Are Getting Slower - -This may be caused by the way the storage format of Git interacts with the way the Mendix model stores changes, which can accumulate substantial disk space over time. Studio Pro periodically optimizes your repository if [automatic repository optimization](/refguide/preferences-dialog/#optimization) is enabled. - -You can run `git gc` in the command line to manually optimize the repository. `git gc` runs a number of housekeeping tasks, but primarily pack files are created. Pack files store just the changes to the files, which reduces the amount of data which needs to be stored. - -## Cloning my Project Takes a Long Time - -Cloning or downloading your app consists of several steps. First the required data is downloaded from the server and then a local unpacking process is executed. The duration of the clone process depends on your repository size, internet connection and computer performance. In case cloning is taking a very long time, consider changing the [Clone type](/refguide/clone-type/) or [troubleshoot repository size](/refguide/troubleshoot-repository-size/). - ## Can I Use the Subversion Version of the Team Server? No, in Mendix 11, we are supporting only Git-versioned apps. You need to migrate your SVN app to Git to use Mendix 11. For more information on how to migrate, see [Migrate to Git](/developerportal/general/migrate-to-git/) in *Apps*. diff --git a/content/en/docs/refguide/version-control/configure/auto-fetch.md b/content/en/docs/refguide/version-control/configure/auto-fetch.md index 96a59fb7216..78285d668fd 100644 --- a/content/en/docs/refguide/version-control/configure/auto-fetch.md +++ b/content/en/docs/refguide/version-control/configure/auto-fetch.md @@ -1,5 +1,5 @@ --- -title: "Automatic Fetching" +title: "Enabling Automatic Fetching" url: /refguide/auto-fetch/ weight: 20 #If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. diff --git a/content/en/docs/refguide/version-control/configure/clone-type.md b/content/en/docs/refguide/version-control/configure/clone-type.md index 1062e95dfbc..fb635415b74 100644 --- a/content/en/docs/refguide/version-control/configure/clone-type.md +++ b/content/en/docs/refguide/version-control/configure/clone-type.md @@ -1,5 +1,5 @@ --- -title: "Clone Type" +title: "Selecting the Clone Type" url: /refguide/clone-type/ weight: 40 description: Describes full and partial clone types for Git. diff --git a/content/en/docs/refguide/version-control/configure/git-storage-optimization-dialog.md b/content/en/docs/refguide/version-control/configure/git-storage-optimization-dialog.md index f847ed604d9..92e236b9121 100644 --- a/content/en/docs/refguide/version-control/configure/git-storage-optimization-dialog.md +++ b/content/en/docs/refguide/version-control/configure/git-storage-optimization-dialog.md @@ -1,5 +1,5 @@ --- -title: "Git Storage Optimization" +title: "Optimizing Git Storage" url: /refguide/git-storage-optimization-dialog/ weight: 30 #If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/_index.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/_index.md index 681f9384573..7ed29d33ef8 100644 --- a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/_index.md +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/_index.md @@ -11,495 +11,4 @@ description: "Describes how to work with version control and how to resolve some This document describes how to use version control in Mendix Studio Pro. -For more information on related concepts and the theory behind how version control works in Mendix, see [Version Control](/refguide/version-control/). - -## Day-to-Day Development - -Let us say you have a working copy of an app on disk. You make changes to the app and save them. Saved changes are not immediately visible to others. The documents, folders, and modules that have been changed can be identified by looking at the **status**. - -When you are happy with a set of changes, you commit and push them to the remote repository (Team Server). Others can then choose to update/pull and retrieve those changes. - -You can **update/pull** your working copy with changes committed by others. - -You can also see a **history** of all the changes that have been committed, no matter who committed them. - -### Status {#status} - -The status of your app is a summary of all the changes in your working copy when compared with the original (the original version is the version you pulled from the remote repository before making your changes (or the newly created app if you have not pulled anything yet). Studio Pro shows the status both in the **App Explorer** and in the **Changes** pane. - -The **App Explorer** shows an icon in front of items (such as documents, folders, and modules) to present that are changed in some way. The different icons indicate the different kinds of changes which have been made. - -| Icon | Meaning | -| --- | --- | -| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/no-changes.png" class="no-border" >}} | Nothing happened to this item. It is unchanged with the respect to the original. | -| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-modified.png" class="no-border" >}} | You modified this item. | -| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-added.png" class="no-border" >}} | You added this item. | -| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-moved.png" class="no-border" >}} | You moved this item to another position in the app tree. | -| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-deleted.png" class="no-border" >}} | You deleted this item. | -| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-conflicting.png" class="no-border" >}} | You and somebody else made conflicting changes to this item. For more information, see the [Dealing With Conflicts](#conflicts) section below. | - -{{% alert color="info" %}} -In the **App Explorer**, there is only room for one icon for each item. If an item is both modified and moved, it is shown as modified with a yellow icon. -{{% /alert %}} - -For example, the microflow **ChangePassword** has been modified. Also a new folder called **Flows** was added and all microflows, including the modified microflow, were moved into this folder. The new folder gets a green icon, and the module containing those changes is depicted with a yellow icon. The microflows which were moved but had not been modified get a blue icon. The modified microflow **ChangePassword** gets a yellow icon. This helps you to quickly see where in the app the changes are. - -In the **Changes** pane, you can find more detailed information. There is an entry for each change to an item. If a document is both modified and moved, there are two lines for that document. The pane also shows items that were deleted, something the app explorer cannot do. For more information, see [Changes Pane](/refguide/changes-pane/). - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/changes-pane.png" max-width=80% >}} - -If you also changed Java source code, added widgets, or made other changes that affect files other than the app file, you will see entry for each changed file. You can right-click the entry and click **Open containing folder** to open the folder with the file on disk. For files with the **Modified** status, you can use **Compare with original** that opens an external tool to show the differences. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/changes-pane-file-changes.png" >}} - -{{% alert color="info" %}} -An external file comparison tool can be set in **Preferences** > **Version control** > **General** > **File comparison** > **Executable**. - -A tool you can consider using is TortoiseGitMerge, shipped as part of [TortoiseGit](https://tortoisegit.org/download/). It is installed by default on this path: *C:\Program Files\TortoiseGit\bin\TortoiseGitMerge.exe*. -{{% /alert %}} - -{{% alert color="info" %}} -Comparing files on disk with the original is currently not supported on macOS. -{{% /alert %}} - -{{% alert color="info" %}} -When you successfully commit your app, this becomes the new original and all the change information is removed from the **App Explorer** and the **Changes** pane. -{{% /alert %}} - -### Committing - -Sending changes to the local repository is called committing. The idea is that you commit small, consistent pieces of work to the repository. Mendix recommends committing your changes often. Preferably, the versions in the repository are always error-free. Studio Pro warns against committing while there are errors in your app. - -To commit your changes, click the **Commit** button in the **Changes** pane, or choose the **Version Control** > **Commit** menu item. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-button.png" max-width=60% alt="Commit Button" >}} - -Git only creates a local commit. To submit your local commit (or commits) to the remote repository, you need to **push** your changes to the remote repository. You can choose between committing and pushing right away or committing locally. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/local-repo-and-team-server.png" alt="Local Repository and Team Server" class="no-border" >}} - -For example, you are developing a feature together with another developer on the same branch. You both have the same starting point (3). When your colleague commits a change, you can choose to retrieve these changes and integrate them. To enable this, developers first need to commit existing changes locally (6), so that the changes can be automatically merged when they are retrieved by other developers. After this, you commit the merged result, and optionally push the merged result (7) to be used by your colleague. Because changes are already explicitly committed, you can always see what you changed and you cannot accidentally override your local changes when you are resolving conflicts. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/incoming-changes.png" alt="Incoming changes in Git" class="no-border" >}} - -In general, it is a good idea to commit after implementing one feature or fixing one bug. By committing often, your work is integrated with the work of others regularly. The benefits of committing include the following: - -* If any conflicts arise, the changes are still fresh in your mind -* Revisions are easier to understand -* If you ever need to revert something, you can revert a small chunk of work - -Committing results in a new revision in the repository. You can add the following information in Studio Pro when you perform a commit, and this will be attached to the newly created revision: - -* A textual message – this should be a summary of the changes you made. -* A list of stories that relate to the commit; for more information, see [Stories Pane](/refguide/stories-pane/). - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-dialog.png" >}} - -Studio Pro also attaches some information automatically: - -* The person who committed (the **Author**) -* The date and time of the commit -* The list of changed documents, folders, and modules along with the type of the change (for example, **modify** or **add**) -* The version of Studio Pro that was used to commit - -If you also changed Java source code, added widgets, or made other changes that affect files other than the app file, you will see a **Changes on disk** tab that shows you what disk changes you are about to commit. **Open containing folder** opens the folder with the file on disk. For files with the **Modified** status, you can use **Compare with original** that opens an external tool to show the differences. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-git-changes-on-disk.png" >}} - -{{% alert color="info" %}} -An external file comparison tool can be set in **Preferences** > **Version control** > **General** > **File comparison** > **Executable**. - -A tool you can consider using is TortoiseGitMerge, shipped as part of [TortoiseGit](https://tortoisegit.org/download/). It is installed by default on this path: *C:\Program Files\TortoiseGit\bin\TortoiseGitMerge.exe*. -{{% /alert %}} - -{{% alert color="info" %}} -Comparing files on disk with the original is currently not supported on macOS. -{{% /alert %}} - -Committing is only allowed if your working copy is up to date with the repository. If someone else committed a change since the last time you pulled, you will have to pull first (this process is called **Commit and Combine** in the [Commit](/refguide/commit-dialog/#combine) dialog box). This is because the revision you create with the commit should incorporate both your changes and the changes by the other person. Updating will combine the latest changes in the repository with your changes. After reviewing the result and fixing any conflicts, you can commit again. - -### Pushing {#pushing} - -Pushing is sending local commits from your local repository to the remote repository (Team Server). After committing, you need to push the committed changes if you want them to be accessible to others. By default, this is done when committing, but it is possible to wait for this step until later. - -To push changes, select **Version Control** > **Push** or simply use the **Commit and Push** button in the **Commit** dialog box. In this case changes are pushed automatically when you commit them: - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-git.png" >}} - -#### Push Fast-Forward Only - -While you were working on your branch, somebody may have pushed their changes to the same branch on the server already. In this case, pushing is not possible and you will need to take further action first. - -In Studio Pro, [automatic fetching](/refguide/auto-fetch/) can be used to discover changes on the server. If at the moment when you click **Commit** Studio Pro knows that there are remote changes, the commit dialog will contain a note about this, and the **Commit and Push** button will be replaced by **Commit and combine**. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-dialog-incoming.png" >}} - -If the changes are discovered during the push, an information dialog with instructions is shown. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-pull-first-dialog.png" class="no-border" >}} - -Git prevents you from pushing your changes if it sees your changes and the remote changes as potentially conflicting. In this diagram, you see that Git does not know how to combine commits #3 and #4. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/server-your-work.png" alt="The local changes consist of commits 1, 3, while the remote server has commits 1, 2, and 4 on the same branch." class="no-border" >}} - -There are two ways for Studio Pro to combine the commits: **Rebase** (default) and **Merge**. For more information, see [Combining Changes and Conflict Resolution](/refguide/merge-algorithm/#combine-changes). - -### Pulling - -Pulling retrieves the latest changes from the remote repository. You need to do this to incorporate any changes made by others that are not yet in your working copy before you can commit your changes to the repository. It is advisable to frequently update so that the number of changes you retrieve is small. - -To update the working copy of your app, click **Pull** in the **Changes** pane, or choose the **Version Control** > **Pull** menu item. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/pull-button.png" max-width=60% alt="Pull Button" >}} - -Changes you receive from the remote repository when pulling are combined with the changes you have made to your working copy (if any). Afterwards, your working copy will contain both your changes and the changes you received. As part of the pull, the original of your working copy is updated as well. - -For example, if the last time you pulled you received all changes up to and including revision N, this means that the original for your working copy is revision N. Since you started making changes to your working copy, other people on your team have made another three commits (X, Y, and Z). If you now pull, you will receive those changes and Z will be the new *original* to which your changes are compared. - -Usually, combining your changes with the latest revision from the repository is done automatically. For example, one person may add a page while you are changing a microflow. If the changes are too close, however, a conflict can arise. For example, if one of your team has changed the properties of the same data view that you have also changed, you will have to resolve such conflicts before you can commit. For information on how to do this, see [Combining Changes and Conflict Resolution](/refguide/merge-algorithm/). - -If your team is committing often, you then should pull often. Frequent pulling has the benefit that you receive fewer changes with each pull so that integrating those changes with your work is easier. - -### History {#history} - -The history of the app is a list of all revisions that have been committed. To view the history of the app, click the **History** button in the **Changes** pane, or choose the **Version Control** > **History** menu item. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/history-button.png" max-width=60% alt="History Button" >}} - -For Git-based applications, revisions are sorted according to the commit history, which sometimes does not reflect the chronological order due to Git's decentralized nature and local commits. The **History** dialog box shows the revision number, date, time, author, and message of each revision. - -{{% alert color="warning" %}} - -The [Name and Email settings](/refguide/preferences-dialog/#name) can be adjusted by the user and are not used for authenticating with the version control server. If you notice a suspicious value in the commit history, it is likely a private email address set through another tool in the global Git configuration, but the user has been authenticated as usual. - -{{% /alert %}} - -Select a revision to see additional details, such as related stories, changed documents, Studio Pro version, and changes on disk. Icons summarize the kinds of changes that happened in the app. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/history-of-dialog.png" class="no-border" >}} - -## Reverting Changes {#revert-changes} - -In case you want to undo changes that have been made, it is important to understand the difference between uncommitted changes, and committed changes that have been pushed to the server. Uncommitted work can simply be reverted, while committed work requires a new **Reverse commit** to undo. - -### Reverting Uncommitted Changes - -Changes that have not yet been committed can be reverted. For example, that you have made a lot of changes to a page and you are not happy with the result. You can revert the page to the original state, that is, the state of the page before you started making changes. - -Deletes of documents, folders, and modules can also be reverted. This brings them back into the app. Note that you will get back the latest version you have committed. For example, if you commit, make some changes to a microflow, and then delete the microflow, reverting the delete restores the microflow without the changes that you made. - -You can revert changes in the **Changes** pane, from **Version Control** > **Revert All Changes**, or from the right-click menu on the document you want to revert. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/revertx2.png" alt="Two ways of reverting" class="no-border" >}} - -{{% alert color="info" %}} -You can also **Revert All Changes** while [merging](#merge). This will restore your app to the most recent commit, discarding changes creating by the merging process. -{{% /alert %}} - -### Reverting a Previous Commit {#revert-previous-commit} - -Changes that have been committed and pushed to the server can never be deleted from the history. However, you can make another commit to revert the changes. This is called **Reverse commit** in Studio Pro. - -Select the **Version Control** menu > **Revert a Commit...** to revert a commit. This will create original changes "in reverse", which you can commit and push to the server. - -{{% alert color="warning" %}} -Reverting a commit creates a new commit that undoes the changes introduced by the original commit. This may lead to unexpected results depending on the context of the original commit. - -* **Cherry picking and reverting** – If you used [Cherry Pick](/refguide/merge-dialog/#cherry-pick) to apply a commit from another branch to the current branch, and then you revert that commit, the changes from the cherry-pick will not be reapplied when merging the full branch. This happens because the revert commit explicitly negates the cherry-picked changes, and Git recognizes them as already addressed. -* **Merging and reverting** – If you [merged another branch](/refguide/version-control/#merging-branches) into the current branch and then reverted the merge commit, merging the same branch again will not reapply its changes. Git identifies that the merge was undone and prevents those changes from being reapplied. -{{% /alert %}} - -Reverting changes is done with one commit at a time. If you want to revert multiple commits, you can do that by reverting the latest commit, then the previous one, etc, one by one. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/revert-changes-git.png" class="no-border" >}} - -#### Reverse Merging - -You can also revert a commit where another branch was merged into the current branch. Reverting a merge removes the changes introduced by that merge, making it appear as if they never happened. For example, if the merge added a new page, reverting it will remove the page locally. - -Just like with a normal merge, conflicts can occur when reverting a merge. For example, if later commits change the new page, the reverse merge will result in a conflict. Once you resolved the conflict, you can commit the changes and push them to the remote repository. - -## Dealing With Conflicts {#conflicts} - -If you update/pull your app and the changes cannot be merged automatically, you will receive a message telling you that there are conflicts. A conflict arises when two changes cannot be combined. - -For more information, see [Combining Changes and Conflict Resolution](/refguide/merge-algorithm/). - -## Using Branches - -A repository (remote or local) can contain a number of development lines. Each development line offers independent development from the other development lines. In the simple case there is just one development line called the main line. All development then happens inside that one line. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/main-branch-line.png" class="no-border" >}} - -It is often convenient to have more than one development line. For example, one development line is for fixing bugs in the currently deployed version of your app and another line is where you develop new functionality. If you then find a bug in the deployed version, you can fix it in the corresponding development line irrespective of the state of the development line where new functionality is developed. For more information about branches, see the [Branches](/refguide/version-control/#branches) section in *Version Control*. - -### Working with Branches in Studio Pro - -This section outlines how to create branches in Studio Pro. It also recommends some [Branching Best-Practices](#branching-best-practices) when developing Mendix apps. - -#### Branching - -Development lines other than the main line are called branch lines. You can consider developing new features in the main line and using branch lines for fixing bugs in versions that have been deployed. This is the scenario Studio Pro makes easy but other scenarios for more complex apps are supported as well. - -You can create branch lines from the **Branch Line Manager** which you can find at **Version Control > Manage Branch Lines...**. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/create-branch-line.png" class="no-border" >}} - -The most common examples on using branch lines are [patching a deployed application](#patch) and [developing a new feature](#new-feature). - -##### Patching a Deployed Application {#patch} - -If you want to add some functionality to a deployed application or you want to fix a bug in it, you can do so without interfering with other development. - -1. Determine the version of the deployed application. This information is in the Mendix Portal. Alternatively, you can find the version in the *metadata.json* file in the **model** subfolder of your deployment package (mda) archive, for example, `"ModelVersion": "1.0.0.16"`. -2. Choose **Version Control > Manage Branch Lines...** and create a branch based on the tag with the version number as its name. - - {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/create-from-tag.png" class="no-border" >}} - -3. Add the functionality or fix the bug in this newly created branch. -4. Testing that things work as intended. -5. Create a new deployment archive with a higher version number (increase patch or minor version). - -{{% alert color="info" %}} -We advise you to merge the fixed maintenance branch into the main line quickly, if required. If the merge is too complicated to be made automatically, because the main line has changed too much, you will know how to apply the fix by hand to the main line as the changes will still be fresh in your mind. - -Of course, not all maintenance fixes need to be merged to the main line. Sometimes, it is a fix of something that was completely redesigned or eliminated in the main line. In this case, merging is unnecessary. -{{% /alert %}} - -##### Developing a New Feature Independently {#new-feature} - -Another reason for creating a branch is to develop a big new feature without interfering with other development. This gives you the freedom to commit a half-implemented feature, possibly even with errors, while other people can still commit and update/pull on the main line. Without using a branch line, you would have to constantly make sure that your app is error free and does not break other parts of the system. - -Firstly, select **Version Control > Manage Branch Lines...** and create a branch from a revision of the main line. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/create-branch-line-dialog.png" class="no-border" >}} - -Now work on the branch until the feature is done, commit the completed work and merge your branch back to the main line (for more information on merging, see the [Merging](#merge) section below). - -You can delete the branch after merging it back, if you want. - -#### Merging {#merge} - -If you have multiple development lines, you sometimes want to merge changes from one development line to another. For example, the fix that you made in a branch line for the production version should also be applied to the new 2.0 version you are developing in the main line. You can, of course, do this by hand but Studio Pro can also help you by merging changes from one development line to another. - -Merging is always done while you have a working copy open. The merge will result in extra local changes in that working copy. It is advisable to commit local changes first before merging extra changes into a working copy. Otherwise, the uncommitted local changes and the changes caused by the merge will be combined and it is very hard to untangle them if you are unhappy with the merge. Studio Pro will warn you if you have uncommitted changes. - -Select **Version Control** > **Merge Changes Here**, after that you can select **Cherry Pick** or **Merge feature branch** options. For more information on merge settings, see [Merge Dialog](/refguide/merge-dialog/). - -#### Replacing the Main Line with a Branch Line - -There are two methods for fully replacing your main line with a branch line. - -The first method is to merge the entire branch line into the main line, essentially replacing the main line contents with the branch line contents. This works as long as the branch line is up to date with the main line (to avoid conflicts). To do this, follow these steps: - -1. Select **Version Control** > **Merge Changes Here** > **Merge feature branch**. -2. Select the branch to merge into the main line. - -The second method should be used if the first method is not possible for some reason and you want to "overwrite" the main line with your branch line. To use the second method, follow these steps: - -1. Check out both the main line and the branch line locally. -2. Overwrite all the files in the main line app directory with those of the branch line (except for the *.git* directory). -3. Commit your changes using Studio Pro. -4. Reopen the main line app in Studio Pro only after overwriting the files. - -#### Merging Using Git in the Command Line - -Merging using Git in the command line or a third-party tool is not supported after the introduction of [MPRv2](/refguide/troubleshoot-repository-size/#mpr-format). External tools cannot correctly merge the *.mpr* and *.mxunit* files, which can lead to a corrupted branch. - -In a future release, we are planning to introduce a separate command as part of the [mx Command-Line Tool](/refguide/mx-command-line-tool/) to allow merging on the command line. - -### Branching Best-Practices {#branching-best-practices} - -Depending on your team's size and preferences, you may find some branching strategies better suited than others. Mendix suggests using one of the following three strategies which have increasing complexity and control and different pros and cons. - -* [Trunk-Based (Single Branch Line)](#branching-trunk): straightforward, easy to start with, well-suited for small teams -* [Trunk-Based with Feature Branches](#branching-trunk-and-feature): reduces risk of merge conflicts, well-suited for larger teams and a regular release cadence -* [Advanced Branching](#branching-advanced): guarding quality becomes easier, well-suited for large teams and structured processes - -We recommend starting trunk-based and adopting trunk-based with feature branches next, if needed. Getting a lot of merge conflicts or releasing a first version to production are sensible triggers to move away from solely trunk-based development. - -For experienced teams, or for organizations with stricter processes and/or auditability criteria, the advanced branching approach is recommended. - -In the [tips and tricks](#branching-tricks) section you will find suggestions on how to work with, and manage, branches in an effective way. - -#### Trunk-Based (Single Branch Line) {#branching-trunk} - -In trunk-based development, all developers work on a single branch, typically the "trunk" or "main" branch. Changes are frequently committed to this branch, and developers continuously push their work to the remote repository. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/branching-trunk.png" >}} - -Benefits are: - -* Simplicity: Trunk-based development is straightforward and easy to understand, making it suitable for small teams or projects with less complex requirements. -* Fast feedback: Developers receive immediate feedback on the impact of their changes, helping to identify and resolve issues quickly. -* Reduced merge conflicts: Since developers frequently push their code, the chances of encountering significant merge conflicts are minimized. - -Disadvantages are: - -* Risk of instability: Constant changes to the main branch can introduce instability, especially if proper testing and quality assurance practices are not in place. -* Limited parallel development: The single branch model can limit parallel development efforts, making it challenging to work on multiple features concurrently. -* Difficulty to mitigate issues: When encountering issues on production, it is not possible to deploy a hotfix without also publishing other changes to your app, without creating a branch. - -This approach is best-suited for small teams. - -#### Trunk-Based with Feature Branches {#branching-trunk-and-feature} - -[Trunk-based](#branching-trunk) can also be combined with short-lived feature branches. Developers work on feature branches, which are created from the main branch. Once a feature is complete, it is merged back into the main branch. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/branching-trunk-and-feature.png" >}} - -Benefits are: - -* Limited complexity: This approach is still relatively straightforward and easy to understand for most developers. -* Isolation of changes: Working on feature branches allows developers to isolate their changes, reducing the risk of disrupting the mainline codebase. - -Disadvantages are: - -* Overhead: Separate feature branches can lead to overhead in terms of merging, code review, and testing. - -This approach is the most-used among Mendix customers, and is best-suited for teams with some experience, or teams running into the limitations of trunk-based development. - -#### Advanced Branching {#branching-advanced} - -In branch-based development, there are typically two types of branches: - -* Long-lived branches: main branch, development branch, release branch -* Short-lived branches: feature branches - -Developers work on feature branches, which are merged into the development branch for integration and testing. The release branch is used to prepare for a stable release, while the main branch represents the production-ready codebase. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/branching-advanced.png" >}} - -Benefits are: - -* Isolation of changes: Working on feature branches allows developers to isolate their changes, reducing the risk of disrupting the mainline codebase. -* Parallel development: Multiple features can be developed simultaneously, enhancing productivity. -* Granular control: Different branches provide granular control over the development and release process. -* Stability and quality: The main and release branches are stable and thoroughly tested, ensuring high-quality releases. -* Scalability: This strategy scales well with larger teams and complex projects - -Disadvantages are: - -* Complexity: Managing multiple long-lived branches and their interactions requires careful planning and coordination. -* Overhead: Maintaining separate branches can lead to overhead in terms of merging, code review, and testing. - -This approach is best-suited to large teams or teams preferring a more rigid process. Projects with strict release cycles can also benefit from this approach, as the release branch is always stable. - -#### Tips and Tricks for Working with Branches {#branching-tricks} - -There are several recommendations that make it easier to work with and manage multiple branches. - -* Periodically merge higher-level branches, such as 'development' or 'main', to lower-level branches, such as feature branches. This ensures you already take the most recent stable work into account when developing a feature, preventing larger merge conflicts down the road. -* Note which branch is being used for development in the stories that you are working on, to avoid confusion. You can also implement a naming convention for branch names, such as `feature_[issueNumber]`. -* Where possible, keep different branches on the same version of Studio Pro. -* Make sure that old branches are cleaned up, to prevent accumulating them over time. Ideally you should delete a branch as part of the process of completing a feature. In cases where branches aren't merged in the end, consider cleaning them up periodically. - -## Versioning an App Deployed to the Cloud {#versioning-app} - -### Deploying Locally - -While developing, you can deploy and run your app on your local machine by clicking the menu item **Run** > **Run Locally**. This allows you to test the app as it currently is stored on your local machine. - -### Deploying Your Working Copy - -When you deploy to the cloud, you can choose to use the version of the app stored on your local machine, the working copy and deploy that to the default environment. If you are using the [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/), or other partner cloud (SAP BTP, for example), click **Publish** to commit and push the version of the app stored on your local machine and deploy that to the default environment. - -### Choosing a Specific Development Line and Revision - -It is also possible to choose a specific development line and revision to deploy to the default environment, or to create a package from. - -In this case, Studio Pro will create a fresh checkout of the chosen revision. This means that any team member can always recreate this version of the deployment package. In other words, Studio Pro does not rely on your local files for creating a versioned deployment package. - -{{% alert color="warning" %}} -You can only create a versioned deployment package of changes that have been committed. If you have local changes that you want to deploy in a versioned deployment package, commit them first. -{{% /alert %}} - -When it creates the package, Studio Pro will also create a tag representing this version of your app. If you want to make modifications to this version later, independently of other development which has taken place, you can create a branch based on this tag. The name of the tag is a version number that you choose. - -#### Deploying a Specific Version to a Mendix Licensed Cloud Node - -If you are using Mendix Cloud, you can choose **App** > **Deploy to Licensed Cloud Node** to deploy a specific version. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/deploy-to-cloud.png" class="no-border" >}} - -#### Creating a Deployment Package from a Specific Version - -If you are using a different hosting environment, you create a deployment package using the menu item **App** > **Create Deployment Package**. - -{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/create-deployment-package.png" class="no-border" >}} - -## Working Outside Studio Pro {#working-outside-studio-pro} - -Studio Pro takes care of some file management automatically. If you add or remove custom widgets, they are automatically added or removed from version control too. Some files and directories (for example, deployment and releases directories) are automatically ignored so that they are not committed to version control. - -We advise you to always commit and update/pull inside Studio Pro, because, in this way, useful metadata is added to your revisions. Studio Pro has ways to recover from external updates or merges but it is best to not depend on that. - -### External Tools {#external-tools} - -If you are doing more advanced changes to files, like adding Java actions or resources to your app, you will have to install a separate tool on your computer and perform some operations yourself: you can use [TortoiseGit](https://tortoisegit.org/) (can be downloaded for free). - -{{% alert color="info" %}} -Studio Pro adds metadata on the Mendix version of your app to each revision when you commit or create a branch. Therefore, when committing or merging using third-party tools, it may no longer be possible to deploy to Mendix Cloud. This can be fixed by making a commit using Studio Pro so that the correct metadata is present again. -{{% /alert %}} - -{{% alert color="warning" %}} -Manually modifying files belonging to the [*.mpr* storage format](/refguide/version-control/#mpr-format) such as the *.mpr* file or the *mprcontents* directory (for example, when resolving file conflicts through third-party tooling), will lead to a corrupted state. To recover from a corrupted state a previous commit will need to be restored. -{{% /alert %}} - -{{% alert color="warning" %}} -Studio Pro automatically performs the necessary post-processing steps when you download a Git clone through its user interface. Using the Git command line to create a Git clone or using a clone created by a third-party tool in Studio Pro is not supported. -{{% /alert %}} - -### Authenticating to Team Server {#authenticating} - -When using external tools, you might be asked to authenticate separately to Team Server. - -Connecting to Git is done using a personal access token (PAT). For more information on how to create a PAT, see the [Personal Access Tokens](/mendix-profile/user-settings/#pat) section of *Mendix Profile*. - -To connect to Git, you need to use the following URL and credentials: - -* URL: `https://git.api.mendix.com/.git` -* Username: your Mendix account username (alternatively, you can use the word *pat* as your username) -* Password: the PAT you created – the PAT must include the scopes `mx:modelrepository:repo:write`, `mx:modelrepository:repo:read`, and/or `mx:modelrepository:write` under *Model Repository* - -### Adding and Deleting Files and Directories - -If you add or delete files (or directories) using Windows Explorer, Studio Pro automatically adds or deletes these from version control too. A folder is no longer tracked if all the files in the folder are removed. - -Make sure you use the **Export** feature of TortoiseGit if you are copying a directory that is already under version control in your app. - -### Branching and Deploying - -If you perform branching outside of Studio Pro, you will not be able to immediately deploy to Mendix Cloud. That is because Studio Pro adds metadata about the Mendix version of your app to each revision when you commit or create a branch, which is needed by the Mendix Cloud deployment. Branching outside of Studio Pro means that metadata is missing from your branch, thus your app cannot successfully be deployed. - -To fix this, make a small commit on your branch in Studio Pro (for example, changing a documentation field). Studio Pro will then add the metadata that Mendix Cloud deployment requires, and you will be able to deploy your app. - -### Reverting Accidental Studio Pro App Model Upgrade - -When working in different apps with different Studio Pro versions, you may one day find yourself with an app model upgraded and committed to a newer Studio Pro version, while the rest of your team is not yet ready to upgrade. - -To revert this version upgrade of the app model, use the Git tool of your preference to revert the change. - -### Integrating Git in a Build Pipeline - -When building deployment packages in a pipeline outside the Mendix platform, you will need to retrieve a specific commit from the Git server. To avoid downloading the full repository every time you can use a clone with limited depth (*shallow clone*). With a minimal amount of data to retrieve, the operation is a lot faster and takes less toll on the version control server. - -You can use the commands below to download a shallow clone. Note that they should only be used to download a single revision, as Studio Pro is not compatible with working on a shallow clone. - -```text -# make a new blank repository in the current directory -git init - -# add a remote -git remote add origin url://to/source/repository - -# fetch a commit (or branch or tag) of interest with limited history -git fetch --depth 1 origin - -# reset this repository's master branch to the commit of interest -git reset --hard FETCH_HEAD -``` - -## Read More - -* [Advanced Branching and Merging Strategies](https://www.mendix.com/blog/advanced-branching-merging-strategies-part-1-2/) +For more information on how version control works in Mendix, see [Version Control](/refguide/version-control/). \ No newline at end of file diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/deploy-external.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/deploy-external.md new file mode 100644 index 00000000000..053ed2018d5 --- /dev/null +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/deploy-external.md @@ -0,0 +1,80 @@ +--- +title: "Deploying Packages with External Tools" +url: /refguide/using-version-control-in-studio-pro/ +weight: 80 +description: "Describes how to work external tools to deploy packages." +--- + +## Introduction + +Studio Pro takes care of some file management automatically. If you add or remove custom widgets, they are automatically added or removed from version control too. Some files and directories (for example, deployment and releases directories) are automatically ignored so that they are not committed to version control. + +We advise you to always commit and update/pull inside Studio Pro, because, in this way, useful metadata is added to your revisions. Studio Pro has ways to recover from external updates or merges but it is best to not depend on that. + +### External Tools {#external-tools} + +If you are doing more advanced changes to files, like adding Java actions or resources to your app, you will have to install a separate tool on your computer and perform some operations yourself: you can use [TortoiseGit](https://tortoisegit.org/) (can be downloaded for free). + +{{% alert color="info" %}} +Studio Pro adds metadata on the Mendix version of your app to each revision when you commit or create a branch. Therefore, when committing or merging using third-party tools, it may no longer be possible to deploy to Mendix Cloud. This can be fixed by making a commit using Studio Pro so that the correct metadata is present again. +{{% /alert %}} + +{{% alert color="warning" %}} +Manually modifying files belonging to the [*.mpr* storage format](/refguide/version-control/#mpr-format) such as the *.mpr* file or the *mprcontents* directory (for example, when resolving file conflicts through third-party tooling), will lead to a corrupted state. To recover from a corrupted state a previous commit will need to be restored. +{{% /alert %}} + +{{% alert color="warning" %}} +Studio Pro automatically performs the necessary post-processing steps when you download a Git clone through its user interface. Using the Git command line to create a Git clone or using a clone created by a third-party tool in Studio Pro is not supported. +{{% /alert %}} + +### Authenticating to Team Server {#authenticating} + +When using external tools, you might be asked to authenticate separately to Team Server. + +Connecting to Git is done using a personal access token (PAT). For more information on how to create a PAT, see the [Personal Access Tokens](/mendix-profile/user-settings/#pat) section of *Mendix Profile*. + +To connect to Git, you need to use the following URL and credentials: + +* URL: `https://git.api.mendix.com/.git` +* Username: your Mendix account username (alternatively, you can use the word *pat* as your username) +* Password: the PAT you created – the PAT must include the scopes `mx:modelrepository:repo:write`, `mx:modelrepository:repo:read`, and/or `mx:modelrepository:write` under *Model Repository* + +### Adding and Deleting Files and Directories + +If you add or delete files (or directories) using Windows Explorer, Studio Pro automatically adds or deletes these from version control too. A folder is no longer tracked if all the files in the folder are removed. + +Make sure you use the **Export** feature of TortoiseGit if you are copying a directory that is already under version control in your app. + +### Branching and Deploying + +If you perform branching outside of Studio Pro, you will not be able to immediately deploy to Mendix Cloud. That is because Studio Pro adds metadata about the Mendix version of your app to each revision when you commit or create a branch, which is needed by the Mendix Cloud deployment. Branching outside of Studio Pro means that metadata is missing from your branch, thus your app cannot successfully be deployed. + +To fix this, make a small commit on your branch in Studio Pro (for example, changing a documentation field). Studio Pro will then add the metadata that Mendix Cloud deployment requires, and you will be able to deploy your app. + +### Reverting Accidental Studio Pro App Model Upgrade + +When working in different apps with different Studio Pro versions, you may one day find yourself with an app model upgraded and committed to a newer Studio Pro version, while the rest of your team is not yet ready to upgrade. + +To revert this version upgrade of the app model, use the Git tool of your preference to revert the change. + +### Integrating Git in a Build Pipeline + +When building deployment packages in a pipeline outside the Mendix platform, you will need to retrieve a specific commit from the Git server. To avoid downloading the full repository every time you can use a clone with limited depth (*shallow clone*). With a minimal amount of data to retrieve, the operation is a lot faster and takes less toll on the version control server. + +You can use the commands below to download a shallow clone. Note that they should only be used to download a single revision, as Studio Pro is not compatible with working on a shallow clone. + +```text +# make a new blank repository in the current directory +git init + +# add a remote +git remote add origin url://to/source/repository + +# fetch a commit (or branch or tag) of interest with limited history +git fetch --depth 1 origin + +# reset this repository's master branch to the commit of interest +git reset --hard FETCH_HEAD +``` + + diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/managing-branches.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/managing-branches.md new file mode 100644 index 00000000000..77fb5ba86e9 --- /dev/null +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/managing-branches.md @@ -0,0 +1,176 @@ +--- +title: "Managing Branches in Studio Pro" +url: /refguide/managing-branches/ +linktitle: "Managing Branches" +weight: 20 +description: "Describes how to work with branches." +--- + +## Introduction + +A repository (remote or local) can contain a number of development lines. Each development line offers independent development from the other development lines. In the simple case there is just one development line called the main line. All development then happens inside that one line. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/main-branch-line.png" class="no-border" >}} + +It is often convenient to have more than one development line. For example, one development line is for fixing bugs in the currently deployed version of your app and another line is where you develop new functionality. If you then find a bug in the deployed version, you can fix it in the corresponding development line irrespective of the state of the development line where new functionality is developed. For more information about branches, see [Version Control Glossary: Branches](/refguide/version-control/glossary/#branches). + +## Working with Branches in Studio Pro + +This section outlines how to create branches in Studio Pro. It also recommends some [Branching Best-Practices](#branching-best-practices) when developing Mendix apps. + +### Branching + +Development lines other than the main line are called branch lines. You can consider developing new features in the main line and using branch lines for fixing bugs in versions that have been deployed. This is the scenario Studio Pro makes easy but other scenarios for more complex apps are supported as well. + +You can create branch lines from the **Branch Line Manager** which you can find at **Version Control > Manage Branch Lines...**. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/create-branch-line.png" class="no-border" >}} + +The most common examples on using branch lines are [patching a deployed application](#patch) and [developing a new feature](#new-feature). + +### Patching a Deployed Application {#patch} + +If you want to add some functionality to a deployed application or you want to fix a bug in it, you can do so without interfering with other development. + +1. Determine the version of the deployed application. This information is in the Mendix Portal. Alternatively, you can find the version in the *metadata.json* file in the **model** subfolder of your deployment package (mda) archive, for example, `"ModelVersion": "1.0.0.16"`. +2. Choose **Version Control > Manage Branch Lines...** and create a branch based on the tag with the version number as its name. + + {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/create-from-tag.png" class="no-border" >}} + +3. Add the functionality or fix the bug in this newly created branch. +4. Testing that things work as intended. +5. Create a new deployment archive with a higher version number (increase patch or minor version). + +{{% alert color="info" %}} +We advise you to merge the fixed maintenance branch into the main line quickly, if required. If the merge is too complicated to be made automatically, because the main line has changed too much, you will know how to apply the fix by hand to the main line as the changes will still be fresh in your mind. + +Of course, not all maintenance fixes need to be merged to the main line. Sometimes, it is a fix of something that was completely redesigned or eliminated in the main line. In this case, merging is unnecessary. +{{% /alert %}} + +### Developing a New Feature Independently {#new-feature} + +Another reason for creating a branch is to develop a big new feature without interfering with other development. This gives you the freedom to commit a half-implemented feature, possibly even with errors, while other people can still commit and update/pull on the main line. Without using a branch line, you would have to constantly make sure that your app is error free and does not break other parts of the system. + +Firstly, select **Version Control > Manage Branch Lines...** and create a branch from a revision of the main line. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/create-branch-line-dialog.png" class="no-border" >}} + +Now work on the branch until the feature is done, commit the completed work and merge your branch back to the main line (for more information on merging, see the [Merging](#merge) section below). + +You can delete the branch after merging it back, if you want. + +### Merging {#merge} + +If you have multiple development lines, you sometimes want to merge changes from one development line to another. For example, the fix that you made in a branch line for the production version should also be applied to the new 2.0 version you are developing in the main line. You can, of course, do this by hand but Studio Pro can also help you by merging changes from one development line to another. + +Merging is always done while you have a working copy open. The merge will result in extra local changes in that working copy. It is advisable to commit local changes first before merging extra changes into a working copy. Otherwise, the uncommitted local changes and the changes caused by the merge will be combined and it is very hard to untangle them if you are unhappy with the merge. Studio Pro will warn you if you have uncommitted changes. + +Select **Version Control** > **Merge Changes Here**, after that you can select **Cherry Pick** or **Merge feature branch** options. For more information on merge settings, see [Merge Dialog](/refguide/merge-dialog/). + +### Replacing the Main Line with a Branch Line + +There are two methods for fully replacing your main line with a branch line. + +The first method is to merge the entire branch line into the main line, essentially replacing the main line contents with the branch line contents. This works as long as the branch line is up to date with the main line (to avoid conflicts). To do this, follow these steps: + +1. Select **Version Control** > **Merge Changes Here** > **Merge feature branch**. +2. Select the branch to merge into the main line. + +The second method should be used if the first method is not possible for some reason and you want to "overwrite" the main line with your branch line. To use the second method, follow these steps: + +1. Check out both the main line and the branch line locally. +2. Overwrite all the files in the main line app directory with those of the branch line (except for the *.git* directory). +3. Commit your changes using Studio Pro. +4. Reopen the main line app in Studio Pro only after overwriting the files. + +### Merging Using Git in the Command Line + +Merging using Git in the command line or a third-party tool is not supported after the introduction of [MPRv2](/refguide/troubleshoot-repository-size/#mpr-format). External tools cannot correctly merge the *.mpr* and *.mxunit* files, which can lead to a corrupted branch. + +In a future release, we are planning to introduce a separate command as part of the [mx Command-Line Tool](/refguide/mx-command-line-tool/) to allow merging on the command line. + +## Branching Best-Practices {#branching-best-practices} + +Depending on your team's size and preferences, you may find some branching strategies better suited than others. Mendix suggests using one of the following three strategies which have increasing complexity and control and different pros and cons. + +* [Trunk-Based (Single Branch Line)](#branching-trunk): straightforward, easy to start with, well-suited for small teams +* [Trunk-Based with Feature Branches](#branching-trunk-and-feature): reduces risk of merge conflicts, well-suited for larger teams and a regular release cadence +* [Advanced Branching](#branching-advanced): guarding quality becomes easier, well-suited for large teams and structured processes + +We recommend starting trunk-based and adopting trunk-based with feature branches next, if needed. Getting a lot of merge conflicts or releasing a first version to production are sensible triggers to move away from solely trunk-based development. + +For experienced teams, or for organizations with stricter processes and/or auditability criteria, the advanced branching approach is recommended. + +In the [tips and tricks](#branching-tricks) section you will find suggestions on how to work with, and manage, branches in an effective way. + +### Trunk-Based (Single Branch Line) {#branching-trunk} + +In trunk-based development, all developers work on a single branch, typically the "trunk" or "main" branch. Changes are frequently committed to this branch, and developers continuously push their work to the remote repository. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/branching-trunk.png" >}} + +Benefits are: + +* Simplicity: Trunk-based development is straightforward and easy to understand, making it suitable for small teams or projects with less complex requirements. +* Fast feedback: Developers receive immediate feedback on the impact of their changes, helping to identify and resolve issues quickly. +* Reduced merge conflicts: Since developers frequently push their code, the chances of encountering significant merge conflicts are minimized. + +Disadvantages are: + +* Risk of instability: Constant changes to the main branch can introduce instability, especially if proper testing and quality assurance practices are not in place. +* Limited parallel development: The single branch model can limit parallel development efforts, making it challenging to work on multiple features concurrently. +* Difficulty to mitigate issues: When encountering issues on production, it is not possible to deploy a hotfix without also publishing other changes to your app, without creating a branch. + +This approach is best-suited for small teams. + +### Trunk-Based with Feature Branches {#branching-trunk-and-feature} + +[Trunk-based](#branching-trunk) can also be combined with short-lived feature branches. Developers work on feature branches, which are created from the main branch. Once a feature is complete, it is merged back into the main branch. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/branching-trunk-and-feature.png" >}} + +Benefits are: + +* Limited complexity: This approach is still relatively straightforward and easy to understand for most developers. +* Isolation of changes: Working on feature branches allows developers to isolate their changes, reducing the risk of disrupting the mainline codebase. + +Disadvantages are: + +* Overhead: Separate feature branches can lead to overhead in terms of merging, code review, and testing. + +This approach is the most-used among Mendix customers, and is best-suited for teams with some experience, or teams running into the limitations of trunk-based development. + +### Advanced Branching {#branching-advanced} + +In branch-based development, there are typically two types of branches: + +* Long-lived branches: main branch, development branch, release branch +* Short-lived branches: feature branches + +Developers work on feature branches, which are merged into the development branch for integration and testing. The release branch is used to prepare for a stable release, while the main branch represents the production-ready codebase. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/branching-advanced.png" >}} + +Benefits are: + +* Isolation of changes: Working on feature branches allows developers to isolate their changes, reducing the risk of disrupting the mainline codebase. +* Parallel development: Multiple features can be developed simultaneously, enhancing productivity. +* Granular control: Different branches provide granular control over the development and release process. +* Stability and quality: The main and release branches are stable and thoroughly tested, ensuring high-quality releases. +* Scalability: This strategy scales well with larger teams and complex projects + +Disadvantages are: + +* Complexity: Managing multiple long-lived branches and their interactions requires careful planning and coordination. +* Overhead: Maintaining separate branches can lead to overhead in terms of merging, code review, and testing. + +This approach is best-suited to large teams or teams preferring a more rigid process. Projects with strict release cycles can also benefit from this approach, as the release branch is always stable. + +### Tips and Tricks for Working with Branches {#branching-tricks} + +There are several recommendations that make it easier to work with and manage multiple branches. + +* Periodically merge higher-level branches, such as 'development' or 'main', to lower-level branches, such as feature branches. This ensures you already take the most recent stable work into account when developing a feature, preventing larger merge conflicts down the road. +* Note which branch is being used for development in the stories that you are working on, to avoid confusion. You can also implement a naming convention for branch names, such as `feature_[issueNumber]`. +* Where possible, keep different branches on the same version of Studio Pro. +* Make sure that old branches are cleaned up, to prevent accumulating them over time. Ideally you should delete a branch as part of the process of completing a feature. In cases where branches aren't merged in the end, consider cleaning them up periodically. diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/peer-review.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/peer-review.md new file mode 100644 index 00000000000..2efe5c2497f --- /dev/null +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/peer-review.md @@ -0,0 +1,29 @@ +--- +title: "Peer Reviewing Changes" +url: /refguide/peer-reviewing/ +linktitle: "Peer Reviewing" +weight: 60 +description: "Describes how to work with version control and how to resolve some issues which may arise." +--- + +## Introduction + +To review the changes for a particular revision, use the **History** menu. + +### History {#history} + +The history of the app is a list of all revisions that have been committed. To view the history of the app, click the **History** button in the **Changes** pane, or choose the **Version Control** > **History** menu item. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/history-button.png" max-width=60% alt="History Button" >}} + +For Git-based applications, revisions are sorted according to the commit history, which sometimes does not reflect the chronological order due to Git's decentralized nature and local commits. The **History** dialog box shows the revision number, date, time, author, and message of each revision. + +{{% alert color="info" %}} + +The [Name and Email settings](/refguide/preferences-dialog/#name) can be adjusted by the user and are not used for authenticating with the version control server. If you notice a suspicious value in the commit history, it is likely a private email address set through another tool in the global Git configuration, but the user has been authenticated as usual. + +{{% /alert %}} + +Select a revision to see additional details, such as related stories, changed documents, Studio Pro version, and changes on disk. Icons summarize the kinds of changes that happened in the app. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/history-of-dialog.png" class="no-border" >}} \ No newline at end of file diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/push-pull.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/push-pull.md new file mode 100644 index 00000000000..b90efd749c6 --- /dev/null +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/push-pull.md @@ -0,0 +1,163 @@ +--- +title: "Pushing, Pulling, and Comitting" +url: /refguide/pushing-pulling/ +weight: 30 +description: "Describes how to push, pull, and commit your changes." +--- + +## Introduction + +This document describes how to use version control in Mendix Studio Pro. + +For more information on related concepts and the theory behind how version control works in Mendix, see [Version Control](/refguide/version-control/). + +## Day-to-Day Development + +Let us say you have a working copy of an app on disk. You make changes to the app and save them. Saved changes are not immediately visible to others. The documents, folders, and modules that have been changed can be identified by looking at the **status**. + +When you are happy with a set of changes, you commit and push them to the remote repository (Team Server). Others can then choose to update/pull and retrieve those changes. + +You can **update/pull** your working copy with changes committed by others. + +You can also see a **history** of all the changes that have been committed, no matter who committed them. + +### Status {#status} + +The status of your app is a summary of all the changes in your working copy when compared with the original (the original version is the version you pulled from the remote repository before making your changes (or the newly created app if you have not pulled anything yet). Studio Pro shows the status both in the **App Explorer** and in the **Changes** pane. + +The **App Explorer** shows an icon in front of items (such as documents, folders, and modules) to present that are changed in some way. The different icons indicate the different kinds of changes which have been made. + +| Icon | Meaning | +| --- | --- | +| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/no-changes.png" class="no-border" >}} | Nothing happened to this item. It is unchanged with the respect to the original. | +| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-modified.png" class="no-border" >}} | You modified this item. | +| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-added.png" class="no-border" >}} | You added this item. | +| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-moved.png" class="no-border" >}} | You moved this item to another position in the app tree. | +| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-deleted.png" class="no-border" >}} | You deleted this item. | +| {{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/item-conflicting.png" class="no-border" >}} | You and somebody else made conflicting changes to this item. For more information, see the [Dealing With Conflicts](#conflicts) section below. | + +{{% alert color="info" %}} +In the **App Explorer**, there is only room for one icon for each item. If an item is both modified and moved, it is shown as modified with a yellow icon. +{{% /alert %}} + +For example, the microflow **ChangePassword** has been modified. Also a new folder called **Flows** was added and all microflows, including the modified microflow, were moved into this folder. The new folder gets a green icon, and the module containing those changes is depicted with a yellow icon. The microflows which were moved but had not been modified get a blue icon. The modified microflow **ChangePassword** gets a yellow icon. This helps you to quickly see where in the app the changes are. + +In the **Changes** pane, you can find more detailed information. There is an entry for each change to an item. If a document is both modified and moved, there are two lines for that document. The pane also shows items that were deleted, something the app explorer cannot do. For more information, see [Changes Pane](/refguide/changes-pane/). + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/changes-pane.png" max-width=80% >}} + +If you also changed Java source code, added widgets, or made other changes that affect files other than the app file, you will see entry for each changed file. You can right-click the entry and click **Open containing folder** to open the folder with the file on disk. For files with the **Modified** status, you can use **Compare with original** that opens an external tool to show the differences. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/changes-pane-file-changes.png" >}} + +{{% alert color="info" %}} +An external file comparison tool can be set in **Preferences** > **Version control** > **General** > **File comparison** > **Executable**. + +A tool you can consider using is TortoiseGitMerge, shipped as part of [TortoiseGit](https://tortoisegit.org/download/). It is installed by default on this path: *C:\Program Files\TortoiseGit\bin\TortoiseGitMerge.exe*. +{{% /alert %}} + +{{% alert color="info" %}} +Comparing files on disk with the original is currently not supported on macOS. +{{% /alert %}} + +{{% alert color="info" %}} +When you successfully commit your app, this becomes the new original and all the change information is removed from the **App Explorer** and the **Changes** pane. +{{% /alert %}} + +### Committing + +Sending changes to the local repository is called committing. The idea is that you commit small, consistent pieces of work to the repository. Mendix recommends committing your changes often. Preferably, the versions in the repository are always error-free. Studio Pro warns against committing while there are errors in your app. + +To commit your changes, click the **Commit** button in the **Changes** pane, or choose the **Version Control** > **Commit** menu item. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-button.png" max-width=60% alt="Commit Button" >}} + +Git only creates a local commit. To submit your local commit (or commits) to the remote repository, you need to **push** your changes to the remote repository. You can choose between committing and pushing right away or committing locally. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/local-repo-and-team-server.png" alt="Local Repository and Team Server" class="no-border" >}} + +For example, you are developing a feature together with another developer on the same branch. You both have the same starting point (3). When your colleague commits a change, you can choose to retrieve these changes and integrate them. To enable this, developers first need to commit existing changes locally (6), so that the changes can be automatically merged when they are retrieved by other developers. After this, you commit the merged result, and optionally push the merged result (7) to be used by your colleague. Because changes are already explicitly committed, you can always see what you changed and you cannot accidentally override your local changes when you are resolving conflicts. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/incoming-changes.png" alt="Incoming changes in Git" class="no-border" >}} + +In general, it is a good idea to commit after implementing one feature or fixing one bug. By committing often, your work is integrated with the work of others regularly. The benefits of committing include the following: + +* If any conflicts arise, the changes are still fresh in your mind +* Revisions are easier to understand +* If you ever need to revert something, you can revert a small chunk of work + +Committing results in a new revision in the repository. You can add the following information in Studio Pro when you perform a commit, and this will be attached to the newly created revision: + +* A textual message – this should be a summary of the changes you made. +* A list of stories that relate to the commit; for more information, see [Stories Pane](/refguide/stories-pane/). + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-dialog.png" >}} + +Studio Pro also attaches some information automatically: + +* The person who committed (the **Author**) +* The date and time of the commit +* The list of changed documents, folders, and modules along with the type of the change (for example, **modify** or **add**) +* The version of Studio Pro that was used to commit + +If you also changed Java source code, added widgets, or made other changes that affect files other than the app file, you will see a **Changes on disk** tab that shows you what disk changes you are about to commit. **Open containing folder** opens the folder with the file on disk. For files with the **Modified** status, you can use **Compare with original** that opens an external tool to show the differences. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-git-changes-on-disk.png" >}} + +{{% alert color="info" %}} +An external file comparison tool can be set in **Preferences** > **Version control** > **General** > **File comparison** > **Executable**. + +A tool you can consider using is TortoiseGitMerge, shipped as part of [TortoiseGit](https://tortoisegit.org/download/). It is installed by default on this path: *C:\Program Files\TortoiseGit\bin\TortoiseGitMerge.exe*. +{{% /alert %}} + +{{% alert color="info" %}} +Comparing files on disk with the original is currently not supported on macOS. +{{% /alert %}} + +Committing is only allowed if your working copy is up to date with the repository. If someone else committed a change since the last time you pulled, you will have to pull first (this process is called **Commit and Combine** in the [Commit](/refguide/commit-dialog/#combine) dialog box). This is because the revision you create with the commit should incorporate both your changes and the changes by the other person. Updating will combine the latest changes in the repository with your changes. After reviewing the result and fixing any conflicts, you can commit again. + +### Pushing {#pushing} + +Pushing is sending local commits from your local repository to the remote repository (Team Server). After committing, you need to push the committed changes if you want them to be accessible to others. By default, this is done when committing, but it is possible to wait for this step until later. + +To push changes, select **Version Control** > **Push** or simply use the **Commit and Push** button in the **Commit** dialog box. In this case changes are pushed automatically when you commit them: + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-git.png" >}} + +#### Push Fast-Forward Only + +While you were working on your branch, somebody may have pushed their changes to the same branch on the server already. In this case, pushing is not possible and you will need to take further action first. + +In Studio Pro, [automatic fetching](/refguide/auto-fetch/) can be used to discover changes on the server. If at the moment when you click **Commit** Studio Pro knows that there are remote changes, the commit dialog will contain a note about this, and the **Commit and Push** button will be replaced by **Commit and combine**. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-dialog-incoming.png" >}} + +If the changes are discovered during the push, an information dialog with instructions is shown. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/commit-pull-first-dialog.png" class="no-border" >}} + +Git prevents you from pushing your changes if it sees your changes and the remote changes as potentially conflicting. In this diagram, you see that Git does not know how to combine commits #3 and #4. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/server-your-work.png" alt="The local changes consist of commits 1, 3, while the remote server has commits 1, 2, and 4 on the same branch." class="no-border" >}} + +There are two ways for Studio Pro to combine the commits: **Rebase** (default) and **Merge**. For more information, see [Combining Changes and Conflict Resolution](/refguide/merge-algorithm/#combine-changes). + +### Pulling + +Pulling retrieves the latest changes from the remote repository. You need to do this to incorporate any changes made by others that are not yet in your working copy before you can commit your changes to the repository. It is advisable to frequently update so that the number of changes you retrieve is small. + +To update the working copy of your app, click **Pull** in the **Changes** pane, or choose the **Version Control** > **Pull** menu item. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/pull-button.png" max-width=60% alt="Pull Button" >}} + +Changes you receive from the remote repository when pulling are combined with the changes you have made to your working copy (if any). Afterwards, your working copy will contain both your changes and the changes you received. As part of the pull, the original of your working copy is updated as well. + +For example, if the last time you pulled you received all changes up to and including revision N, this means that the original for your working copy is revision N. Since you started making changes to your working copy, other people on your team have made another three commits (X, Y, and Z). If you now pull, you will receive those changes and Z will be the new *original* to which your changes are compared. + +Usually, combining your changes with the latest revision from the repository is done automatically. For example, one person may add a page while you are changing a microflow. If the changes are too close, however, a conflict can arise. For example, if one of your team has changed the properties of the same data view that you have also changed, you will have to resolve such conflicts before you can commit. For information on how to do this, see [Combining Changes and Conflict Resolution](/refguide/merge-algorithm/). + +If your team is committing often, you then should pull often. Frequent pulling has the benefit that you receive fewer changes with each pull so that integrating those changes with your work is easier. + +## Read More + +* [Mx Command-Line Tool: Merging and Diffing Commands](/refguide/mx-command-line-tool/#merging-and-diffing-commands) \ No newline at end of file diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/merge-algorithm.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/resolving-conflicts.md similarity index 98% rename from content/en/docs/refguide/version-control/using-version-control-in-studio-pro/merge-algorithm.md rename to content/en/docs/refguide/version-control/using-version-control-in-studio-pro/resolving-conflicts.md index 31f41f4123d..21fa63a55a7 100644 --- a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/merge-algorithm.md +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/resolving-conflicts.md @@ -1,11 +1,12 @@ --- -title: "Combining Changes and Conflict Resolution" -linktitle: "Combining Changes and Conflict Resolution" -url: /refguide/merge-algorithm/ -weight: 10 -description: "Describes combining changes with conflict resolution flow." +title: "Combining Changes and Resolving Conflicts" +url: /refguide/resolving-conflicts/ +linktitle: "Resolving Conflicts" +weight: 50 +description: "Describes how to combine changes and resolve conflicts with the conflict resolution flow." #If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. aliases: + - /refguide/merge-algorithm/ - /refguide/new-merge-algorithm - /refguide/rebase-conflict - /refguide/rebase diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/reverting-changes.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/reverting-changes.md new file mode 100644 index 00000000000..d92fa73536d --- /dev/null +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/reverting-changes.md @@ -0,0 +1,48 @@ +--- +title: "Reverting Changes" +url: /refguide/reverting-changes/ +weight: 40 +description: "Describes how to revert changes in Studio Pro Version Control." +# Renamed from version-control-scenarios +--- + +## Introduction + +In case you want to undo changes that have been made, it is important to understand the difference between uncommitted changes, and committed changes that have been pushed to the server. Uncommitted work can simply be reverted, while committed work requires a new **Reverse commit** to undo. + +### Reverting Uncommitted Changes + +Changes that have not yet been committed can be reverted. For example, that you have made a lot of changes to a page and you are not happy with the result. You can revert the page to the original state, that is, the state of the page before you started making changes. + +Deletes of documents, folders, and modules can also be reverted. This brings them back into the app. Note that you will get back the latest version you have committed. For example, if you commit, make some changes to a microflow, and then delete the microflow, reverting the delete restores the microflow without the changes that you made. + +You can revert changes in the **Changes** pane, from **Version Control** > **Revert All Changes**, or from the right-click menu on the document you want to revert. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/revertx2.png" alt="Two ways of reverting" class="no-border" >}} + +{{% alert color="info" %}} +You can also **Revert All Changes** while [merging](#merge). This will restore your app to the most recent commit, discarding changes creating by the merging process. +{{% /alert %}} + +### Reverting a Previous Commit {#revert-previous-commit} + +Changes that have been committed and pushed to the server can never be deleted from the history. However, you can make another commit to revert the changes. This is called **Reverse commit** in Studio Pro. + +Select the **Version Control** menu > **Revert a Commit...** to revert a commit. This will create original changes "in reverse", which you can commit and push to the server. + +{{% alert color="warning" %}} +Reverting a commit creates a new commit that undoes the changes introduced by the original commit. This may lead to unexpected results depending on the context of the original commit. + +* **Cherry picking and reverting** – If you used [Cherry Pick](/refguide/merge-dialog/#cherry-pick) to apply a commit from another branch to the current branch, and then you revert that commit, the changes from the cherry-pick will not be reapplied when merging the full branch. This happens because the revert commit explicitly negates the cherry-picked changes, and Git recognizes them as already addressed. +* **Merging and reverting** – If you [merged another branch](/refguide/version-control/#merging-branches) into the current branch and then reverted the merge commit, merging the same branch again will not reapply its changes. Git identifies that the merge was undone and prevents those changes from being reapplied. +{{% /alert %}} + +Reverting changes is done with one commit at a time. If you want to revert multiple commits, you can do that by reverting the latest commit, then the previous one, etc, one by one. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/revert-changes-git.png" class="no-border" >}} + +#### Reverse Merging + +You can also revert a commit where another branch was merged into the current branch. Reverting a merge removes the changes introduced by that merge, making it appear as if they never happened. For example, if the merge added a new page, reverting it will remove the page locally. + +Just like with a normal merge, conflicts can occur when reverting a merge. For example, if later commits change the new page, the reverse merge will result in a conflict. Once you resolved the conflict, you can commit the changes and push them to the remote repository. \ No newline at end of file diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/version-cloud-app.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/version-cloud-app.md new file mode 100644 index 00000000000..061c903c268 --- /dev/null +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/version-cloud-app.md @@ -0,0 +1,46 @@ +--- +title: "Versioning an App Deployed to the Cloud" +url: /refguide/versioning-cloud-app/ +weight: 70 +description: "Describes how to work with version control in Mendix Cloud apps." +--- + +## Introduction + +[tbd] + +### Deploying Locally + +While developing, you can deploy and run your app on your local machine by clicking the menu item **Run** > **Run Locally**. This allows you to test the app as it currently is stored on your local machine. + +### Deploying Your Working Copy + +When you deploy to the cloud, you can choose to use the version of the app stored on your local machine, the working copy and deploy that to the default environment. If you are using the [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/), or other partner cloud (SAP BTP, for example), click **Publish** to commit and push the version of the app stored on your local machine and deploy that to the default environment. + +### Choosing a Specific Development Line and Revision + +It is also possible to choose a specific development line and revision to deploy to the default environment, or to create a package from. + +In this case, Studio Pro will create a fresh checkout of the chosen revision. This means that any team member can always recreate this version of the deployment package. In other words, Studio Pro does not rely on your local files for creating a versioned deployment package. + +{{% alert color="warning" %}} +You can only create a versioned deployment package of changes that have been committed. If you have local changes that you want to deploy in a versioned deployment package, commit them first. +{{% /alert %}} + +When it creates the package, Studio Pro will also create a tag representing this version of your app. If you want to make modifications to this version later, independently of other development which has taken place, you can create a branch based on this tag. The name of the tag is a version number that you choose. + +#### Deploying a Specific Version to a Mendix Licensed Cloud Node + +If you are using Mendix Cloud, you can choose **App** > **Deploy to Licensed Cloud Node** to deploy a specific version. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/deploy-to-cloud.png" class="no-border" >}} + +#### Creating a Deployment Package from a Specific Version + +If you are using a different hosting environment, you create a deployment package using the menu item **App** > **Create Deployment Package**. + +{{< figure src="/attachments/refguide/version-control/using-version-control-in-studio-pro/create-deployment-package.png" class="no-border" >}} + +## Read More + +* [Advanced Branching and Merging Strategies](https://www.mendix.com/blog/advanced-branching-merging-strategies-part-1-2/) diff --git a/content/en/docs/refguide/version-control/version-control-troubleshooting/_index.md b/content/en/docs/refguide/version-control/version-control-troubleshooting/_index.md index a3a5aac348d..8d334edd338 100644 --- a/content/en/docs/refguide/version-control/version-control-troubleshooting/_index.md +++ b/content/en/docs/refguide/version-control/version-control-troubleshooting/_index.md @@ -1,7 +1,6 @@ --- title: "Troubleshooting Version Control" url: /refguide/troubleshoot-version-control-issues/ -linktitle: "Troubleshoot Version Control" weight: 90 description: "Presents a list of problems and fixes for version control issues." aliases: @@ -21,6 +20,10 @@ For more information and general help on version control, see the following docu ## Troubleshooting {#troubleshooting} +### Team Server Connectivity Issues + +Mendix Studio Pro needs to connect to the Team Server, where all your apps are stored. If you are having issues connecting to the Team Server, see [Troubleshooting Team Server Issues](/refguide/troubleshoot-team-server-issues/). + ### Getting an Unexpected Error: `The project contains changes that have not been committed yet. Please commit first before attempting to merge again.` {#css-error} {{% alert color="info" %}} @@ -162,3 +165,13 @@ In case of a configuration error, an unknown author may appear in the commit his Other tools on your machine that use the Git configuration, such as a traditional IDE, are typically also capable of changing this Git configuration. If you have chosen a name and email for a hobby project in another IDE, that information may also appear in commits made from Studio Pro. To fix the issue, ensure that responsible users change their Git configuration in [Preferences](/refguide/preferences-dialog/#name). Changing historical commits is not possible within Studio Pro. + +### Retrieve and Commit + Push Actions Are Getting Slower + +This may be caused by the way the storage format of Git interacts with the way the Mendix model stores changes, which can accumulate substantial disk space over time. Studio Pro periodically optimizes your repository if [automatic repository optimization](/refguide/preferences-dialog/#optimization) is enabled. + +You can run `git gc` in the command line to manually optimize the repository. `git gc` runs a number of housekeeping tasks, but primarily pack files are created. Pack files store just the changes to the files, which reduces the amount of data which needs to be stored. + +### Cloning my Project Takes a Long Time + +Cloning or downloading your app consists of several steps. First the required data is downloaded from the server and then a local unpacking process is executed. The duration of the clone process depends on your repository size, internet connection and computer performance. In case cloning is taking a very long time, consider changing the [clone type](/refguide/clone-type/), or follow the steps described in [Troubleshooting Repository Size](/refguide/troubleshoot-repository-size/). \ No newline at end of file From bcdfea7d5ba1c1f781f41e3d12964ce303f08b3c Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Tue, 10 Feb 2026 13:12:41 +0100 Subject: [PATCH 7/7] Update _index.md --- content/en/docs/refguide/version-control/configure/_index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/refguide/version-control/configure/_index.md b/content/en/docs/refguide/version-control/configure/_index.md index 0a55e701e8d..c80e4a1280f 100644 --- a/content/en/docs/refguide/version-control/configure/_index.md +++ b/content/en/docs/refguide/version-control/configure/_index.md @@ -1,7 +1,6 @@ --- title: "Configuring Version Control" url: /refguide/uversion-control/configure/ -linktitle: "Using Version Control" weight: 30 description: "Describes how to configure version control for your Mendix application." --- @@ -12,4 +11,4 @@ This document describes how to configure version control in Mendix Studio Pro. For more information on related concepts and the theory behind how version control works in Mendix, see [Version Control](/refguide/version-control/). -[TBD] \ No newline at end of file +[TBD]