diff --git a/content/en/docs/refguide/modeling/menus/version-control-menu/history-dialog.md b/content/en/docs/refguide/modeling/menus/version-control-menu/history-dialog.md index 9887315abeb..f8fe51c0458 100644 --- a/content/en/docs/refguide/modeling/menus/version-control-menu/history-dialog.md +++ b/content/en/docs/refguide/modeling/menus/version-control-menu/history-dialog.md @@ -41,6 +41,14 @@ For each revision the following information is shown, more information about eac By selecting a revision in this grid, the tabs below the grid will be filled with information about this revision. +### Comparing Revisions + +You can compare any revision to your current working state by right-clicking a revision and selecting **Compare to current state**. This opens the [Comparison Pane](/refguide/comparison-pane/), which shows all differences between the selected revision and your current state, including uncommitted changes. + +{{< figure src="/attachments/refguide/modeling/menus/view-menu/comparison-pane/history-right-click-menu.png" alt="Compare to current state in History pane right-click menu" class="no-border" >}} + +For more information, see [Comparing Revisions](/refguide/comparing-revisions/). + #### Revision{#revision} A unique alphanumeric identifier of the revision in the repository. The revision identifier is the Git hash for the commit and is unique for a whole repository. @@ -95,4 +103,6 @@ This tab shows a list of stories that are related to the changes. * [Version Control](/refguide/version-control/) * [Stories Pane](/refguide/stories-pane/) -* [Using Version Control History](/refguide/version-control-using-history/) \ No newline at end of file +* [Using Version Control History](/refguide/version-control-using-history/) +* [Comparison Pane](/refguide/comparison-pane/) +* [Comparing Revisions](/refguide/comparing-revisions/) \ No newline at end of file diff --git a/content/en/docs/refguide/modeling/menus/view-menu/_index.md b/content/en/docs/refguide/modeling/menus/view-menu/_index.md index ea69700b3dc..0f32d7d344b 100644 --- a/content/en/docs/refguide/modeling/menus/view-menu/_index.md +++ b/content/en/docs/refguide/modeling/menus/view-menu/_index.md @@ -68,6 +68,10 @@ This pane has two levels, so when you zoom into a changed document, you can revi +### Comparison + +The [Comparison](/refguide/comparison-pane/) pane shows the differences between a selected historical revision and your current working state, allowing you to see what documents, elements, and properties changed. + ### History {#history-pane} The non-blocking History pane shows commits in your repository and allows you to search and navigate to modified documents without closing the history view. diff --git a/content/en/docs/refguide/modeling/menus/view-menu/changes-pane.md b/content/en/docs/refguide/modeling/menus/view-menu/changes-pane.md index 2bd1ed96fc1..0164d052384 100644 --- a/content/en/docs/refguide/modeling/menus/view-menu/changes-pane.md +++ b/content/en/docs/refguide/modeling/menus/view-menu/changes-pane.md @@ -9,6 +9,10 @@ description: "Describes the Changes pane in Mendix Studio Pro." For version control enabled apps (apps with Team Server or other Git servers), the **Changes** pane shows the local changes to the app since the last commit. You can commit changes, update to the latest revision, and view the history from it. +{{% alert color="info" %}} +The **Changes** pane shows your local changes since the last commit. To compare any historical revision to your current state, use the [Comparison Pane](/refguide/comparison-pane/) instead. For more information, see [Comparing Revisions](/refguide/comparing-revisions/). +{{% /alert %}} + This pane consists of the following: * The [top bar](#top-bar) contains various buttons, such as **Back**, **Go to**, **Tasks**. @@ -141,4 +145,6 @@ The left and right panes will contain the same information as in [Zoomed-In Leve ## Read More * [Studio Pro Overview](/refguide/studio-pro-overview/) -* [Version Control](/refguide/version-control/) +* [Version Control](/refguide/version-control/) +* [Comparison Pane](/refguide/comparison-pane/) +* [Comparing Revisions](/refguide/comparing-revisions/) diff --git a/content/en/docs/refguide/modeling/menus/view-menu/comparison-pane.md b/content/en/docs/refguide/modeling/menus/view-menu/comparison-pane.md new file mode 100644 index 00000000000..2b05a2fe3ca --- /dev/null +++ b/content/en/docs/refguide/modeling/menus/view-menu/comparison-pane.md @@ -0,0 +1,166 @@ +--- +title: "Comparison Pane" +url: /refguide/comparison-pane/ +weight: 25 +description: "Describes the Comparison Pane in Mendix Studio Pro for comparing a revision to the current state of a version-controlled app." +--- + +## Introduction + +The **Comparison Pane** shows the differences between a selected historical revision and your current working state in a version-controlled app. This pane displays three levels of detail: which documents changed, which elements within those documents changed, and which property values differ. + +This feature requires a version-controlled app. For apps without version control, the Comparison Pane is disabled. + +## Accessing the Comparison Pane + +To compare a revision to your current state: + +1. Open the History pane by clicking **View** > **History**. +2. Right-click any revision in the list. +3. Select **Compare to current state**. + +{{< figure src="/attachments/refguide/modeling/menus/view-menu/comparison-pane/history-right-click-menu.png" alt="Compare to current state option in History pane right-click menu" class="no-border" >}} + +The Comparison Pane opens and shows all differences between the selected revision and your current working state, including any uncommitted changes. + +## Version Compatibility + +{{% alert color="warning" %}} +When comparing revisions created in older versions of Studio Pro, the models are converted on-the-fly to the current Studio Pro version format. Due to this automatic conversion, the displayed older revision may not be 100% identical to the original model. This is a normal part of the version upgrade process and does not affect your actual stored revisions. +{{% /alert %}} + +## Comparison Pane Structure + +The Comparison Pane shows information at three levels: + +* **Level 1** – A list of all documents that differ between the two revisions +* **Level 2** – All elements within a selected document that have changed +* **Level 3** – The specific property values that differ for a selected element + +You can navigate between levels by double-clicking a row or using the **Go to** button. Press Backspace or click **Back** to return to the previous level. + +## Unversioned App State + +If your app does not have version control enabled, all buttons in the Comparison Pane are disabled and a message indicates that version control is required. + +## Loading State + +When starting a comparison or performing other operations that take more than a few seconds, a spinner is displayed to indicate the comparison is loading. + +## Level 1: Document List + +Level 1 displays all documents that differ between the selected revision and your current state. + +{{< figure src="/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level1.png" alt="Comparison Pane Level 1 showing document list" class="no-border" >}} + +### Task Bar + +The task bar contains the following buttons: + +| Button | Action | When Enabled | +|--------|--------|--------------| +| **Back** | Returns to the previous level | Always disabled at Level 1 (kept to prevent layout shift) | +| **Go to** | Opens the selected document and navigates to Level 2/3 | Enabled when a document is selected | +| **Stop comparison** | Closes the comparison and returns to the blank state | Always enabled during an active comparison | + +### Context Menu + +Right-click any cell in the grid to access the **Copy** option, which copies the cell value to your clipboard. + +### Grid Columns + +The document list grid contains the following columns: + +| Column | Description | What It Shows | +|--------|-------------|---------------| +| **Status** | The type of change | An icon and label indicating whether the document was Added, Modified, or Deleted | +| **Item** | The document name | The name of the changed document (for example, a page, microflow, or domain model) | +| **Module** | The module location | The module that contains the document | + +All columns are sortable by clicking the column header. Column widths can be adjusted by dragging the column divider. Hover over any cell to see the full value in a tooltip. + +### Status Types + +The Status column shows one of the following types: + +| Status | Icon | Meaning | When It Appears | +|--------|------|---------|-----------------| +| **Added** | Green circle | A new document was created | The document exists in the current state but not in the selected revision | +| **Modified** | Yellow circle | Changes were made to an existing document | The document exists in both revisions but has differences | +| **Deleted** | Red circle with minus | A document was removed | The document existed in the selected revision but not in the current state | + +The icon and text spacing is consistent with the History Pane style. + +## Level 2 and 3: Element and Property Diffs + +Double-clicking a document in Level 1 navigates to Level 2 and Level 3, which appear side by side. Level 2 shows changed elements, and Level 3 shows the property differences for the selected element. + +{{< figure src="/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level2-3.png" alt="Comparison Pane Level 2 and Level 3 showing element and property differences" class="no-border" >}} + +### Task Bar + +The task bar at Level 2/3 contains the following buttons: + +| Button | Action | When Enabled | +|--------|--------|--------------| +| **Back** | Returns to Level 1 | Always enabled | +| **Go to** | Focuses on the selected element in the document | Enabled when an element is selected; remains active even for deleted elements to support cross-tab navigation | +| **Expand all** | Expands all collapsed property tree rows in Level 3 | Always enabled when viewing Level 3 | +| **Collapse all** | Collapses all expanded property tree rows in Level 3 | Always enabled when viewing Level 3 | +| **Stop comparison** | Closes the comparison and returns to the blank state | Always enabled during an active comparison | + +### Context Menu + +Right-click any cell in either the Level 2 or Level 3 grid to access the **Copy** option. + +### Level 2 Grid + +The Level 2 grid shows all changed elements within the selected document: + +| Column | Description | What It Shows | +|--------|-------------|---------------| +| **Status** | The type of change | An icon and label indicating whether the element was Added, Modified, or Deleted | +| **Item** | The element name | The name of the changed element (for example, a widget, entity, or activity) | + +Hover over any cell to see the full value in a tooltip. + +### Level 3 Grid + +The Level 3 grid shows the property-level differences for the element selected in Level 2: + +| Column | Description | What It Shows | +|--------|-------------|---------------| +| **Property** | The property name | The name of the property that changed, shown as a tree structure | +| **Older** | The value in the selected revision | The property value as it was in the historical revision | +| **Newer** | The value in the current state | The property value as it is in your current working state | + +Property paths are consolidated into a tree view. Grey rows represent intermediate path levels that do not have a direct value. The row order reflects the top-to-bottom, left-to-right order that the corresponding components appear in their dialog boxes. + +### Splitter + +A draggable splitter separates Level 2 and Level 3. Drag the splitter to adjust the space allocated to each level. By default, Level 3 (property differences) is given more space than Level 2 (element list). + +## Opening Documents + +When you click **Go to** or double-click a document entry in Level 1, the document opens as it currently exists in your project. If the document no longer exists in your current state, Level 2/3 is shown but nothing opens in the editor. + +{{% alert color="info" %}} +In a future release (Mendix 11.18), both versions of the document will be opened side by side for visual comparison. For now, only the current version opens. +{{% /alert %}} + +## Refresh Behavior + +When you are comparing a revision to your current state and you save changes to your app, a **Refresh** button appears in the Comparison Pane. Click **Refresh** to update the comparison with your latest saved changes. + +## Stopping a Comparison + +Click the **Stop comparison** button to close the comparison. This action closes the Comparison Pane and returns it to a blank state. Any documents that were opened as part of the comparison remain open in the editor. + +In the blank state, the Comparison Pane displays a message with a link to start a new comparison. The **Go to** and **Stop comparison** buttons are disabled until a new comparison is started. + +## Read More + +* [History](/refguide/history-dialog/) +* [Changes Pane](/refguide/changes-pane/) +* [Comparing Revisions](/refguide/comparing-revisions/) +* [Version Control](/refguide/version-control/) diff --git a/content/en/docs/refguide/version-control/_index.md b/content/en/docs/refguide/version-control/_index.md index 6e838b53fbb..2bc1a5de45c 100644 --- a/content/en/docs/refguide/version-control/_index.md +++ b/content/en/docs/refguide/version-control/_index.md @@ -31,6 +31,12 @@ Currently, Mendix does not support pull or merge requests through the Team Serve * code for Java and JavaScript actions * HTML/CSS for theming +## Comparing Revisions + +Use the [Comparison Pane](/refguide/comparison-pane/) to compare any historical revision to your current working state. This helps you understand what has changed since a specific revision, see the impact of your recent edits, or review what would be affected if you reverted to a past revision. + +For more information, see [Comparing Revisions](/refguide/comparing-revisions/). + ## Frequently Asked Questions ### What Version Control System Is Team Server Built On? {#which-team-server} diff --git a/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/comparing-revisions.md b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/comparing-revisions.md new file mode 100644 index 00000000000..bb0d2e70a67 --- /dev/null +++ b/content/en/docs/refguide/version-control/using-version-control-in-studio-pro/comparing-revisions.md @@ -0,0 +1,137 @@ +--- +title: "Comparing Revisions" +url: /refguide/comparing-revisions/ +weight: 25 +description: "How to compare a historical revision to your current state to understand what changed." +--- + +## Introduction + +The Comparison Pane allows you to compare any historical revision of your version-controlled app to your current working state. This helps you understand what has changed since a specific commit, see the impact of your recent edits, or review what would be affected if you reverted to a past revision. + +The comparison shows three levels of detail: which documents changed, which elements within those documents changed, and which property values differ between the revision and your current state. + +**Key limitation:** You can only compare a selected historical revision to your current working state. It is not possible to compare two arbitrary past revisions to each other. + +This feature is similar to the [Changes Pane](/refguide/changes-pane/), but while the Changes Pane shows your local modifications since your last commit, the Comparison Pane shows differences between any historical revision and your current state. + +## Starting a Comparison + +To compare a historical revision to your current state: + +1. Open the History pane by clicking **View** > **History**. +2. Right-click the revision you want to compare. +3. Select **Compare to current state**. + +The [Comparison Pane](/refguide/comparison-pane/) opens and displays all differences between the selected revision and your current working state, including any uncommitted changes you have made. + +## Version Compatibility + +When you compare revisions created in older versions of Studio Pro, the older revision is automatically converted to the current Studio Pro version format. This conversion allows you to compare across versions, but the displayed older revision may not be 100% identical to the original due to model conversion differences. For more information, see the [Version Compatibility](/refguide/comparison-pane/#version-compatibility) section in *Comparison Pane*. + +## What Gets Compared + +The comparison shows differences between: + +* **Older revision** – The historical revision you selected from the History pane +* **Newer revision** – Your current working state, including all uncommitted changes + +Because the comparison always includes your current uncommitted changes, you can use this feature to see how your recent edits differ from any point in your app's history. + +## Understanding the Comparison Results + +The Comparison Pane shows results at three levels: + +### Document-Level Differences + +At Level 1, you see a list of all documents that differ between the two revisions. Each document has a status: + +* **Added** (green circle) – The document exists in your current state but did not exist in the selected revision +* **Modified** (yellow circle) – The document exists in both versions but has changes +* **Deleted** (red circle with minus) – The document existed in the selected revision but no longer exists in your current state + +### Element-Level Differences + +At Level 2, you see which elements within a document have changed. For example, in a page, you might see which widgets were added, modified, or deleted. In a domain model, you might see which entities or associations changed. + +### Property-Level Differences + +At Level 3, you see the specific property values that differ for a selected element. The grid shows three columns: + +* **Property** – The name of the property (shown as a tree structure for nested properties) +* **Older** – The value in the historical revision +* **Newer** – The value in your current state + +Grey rows in the property tree represent intermediate path levels without a direct value. The properties are ordered to match how they appear in the corresponding dialog boxes. + +## Navigating the Comparison + +Use these methods to navigate through the comparison: + +* **Double-click** a row to drill down to the next level +* **Press Enter** on a selected row to drill down +* **Click the Go to button** to drill down or focus on an element in the document +* **Click the Back button** or **press Backspace** to return to the previous level +* **Use the Expand all button** to expand all property tree nodes in Level 3 +* **Use the Collapse all button** to collapse all property tree nodes in Level 3 + +## Opening Documents + +When you click **Go to** or double-click a document in the comparison, the document opens as it currently exists in your project. This allows you to see the document in context and make further edits if needed. + +If the document no longer exists in your current state (it was deleted), Level 2 and Level 3 are still displayed so you can review what was in the document, but nothing opens in the editor. + +## Refreshing a Comparison + +When you are viewing a comparison and you save changes to your app, a **Refresh** button appears in the Comparison Pane. Click **Refresh** to update the comparison to include your latest saved changes. This allows you to iteratively make changes and see how they affect the comparison without restarting the comparison from scratch. + +## Stopping a Comparison + +Click the **Stop comparison** button in the Comparison Pane to close the comparison. The pane returns to a blank state and is ready for you to start a new comparison. Documents that were opened as part of the comparison remain open in your editor. + +## Common Scenarios + +### What Changed Since This Commit? + +To see all changes made since a specific commit: + +1. Open the History pane and find the commit in question. +2. Right-click the commit and select **Compare to current state**. +3. Review the document, element, and property-level differences. + +This helps you understand the scope of work done since that commit, whether by you or other team members. + +### What Would Reverting to This Revision Undo? + +Before reverting to an older revision, you can preview what would change: + +1. Open the History pane and find the revision you are considering reverting to. +2. Right-click the revision and select **Compare to current state**. +3. Review the differences to understand what would be undone by the revert. + +This helps you make an informed decision about whether reverting is safe or if it would undo important work. + +### Did My Recent Changes Affect This Area? + +To check if your recent uncommitted changes affected a specific area of your app: + +1. Open the History pane and select your most recent commit (HEAD). +2. Right-click and select **Compare to current state**. +3. Look for the documents or elements you are concerned about. + +Because the comparison includes uncommitted changes, you can see the full impact of your current working session. + +## Tips and Tricks + +* **Use Expand all and Collapse all** in Level 3 to quickly show or hide all nested property paths. This is especially useful when comparing complex elements with many properties. +* **Right-click any cell** in the grids and select **Copy** to copy the cell value to your clipboard. This is useful for documenting changes or sharing information with your team. +* **Press Enter to drill down** and Backspace to go back when navigating the comparison. This is faster than using the mouse to click buttons. +* **Understand version conversions** – When comparing older revisions, remember that model conversions may introduce minor differences in how properties are displayed. These do not affect your stored revisions. + +## Read More + +* [Comparison Pane](/refguide/comparison-pane/) +* [History](/refguide/history-dialog/) +* [Changes Pane](/refguide/changes-pane/) +* [Version Control](/refguide/version-control/) +* [Using Version Control History](/refguide/peer-review/) diff --git a/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level1.png b/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level1.png new file mode 100644 index 00000000000..47636e1b331 Binary files /dev/null and b/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level1.png differ diff --git a/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level2-3.png b/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level2-3.png new file mode 100644 index 00000000000..b37aec7bd10 Binary files /dev/null and b/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level2-3.png differ diff --git a/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/history-right-click-menu.png b/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/history-right-click-menu.png new file mode 100644 index 00000000000..cf5bbff69de Binary files /dev/null and b/static/attachments/refguide/modeling/menus/view-menu/comparison-pane/history-right-click-menu.png differ