diff --git a/docs/testing-deployment-publishing/branching-collaboration/branching.md b/docs/testing-deployment-publishing/branching-collaboration/branching.md index b0a958e8..d903166f 100644 --- a/docs/testing-deployment-publishing/branching-collaboration/branching.md +++ b/docs/testing-deployment-publishing/branching-collaboration/branching.md @@ -5,6 +5,7 @@ description: Learn how branching in FlutterFlow allows you to add new features w tags: [Branching, Collaboration] sidebar_position: 1 keywords: [Branching, Collaboration, FlutterFlow, Concepts] +toc_max_heading_level: 4 --- # Branching @@ -183,10 +184,24 @@ During a merge, FlutterFlow compares the changes made in both branches, if the c ::: -### Initiating a merge +### Initiating a Merge -You can initiate a merge in either direction by selecting the **Branch Options** button next to the current branch in the **Branching Menu.** +FlutterFlow currently supports **two merging approaches**: the existing “**Merge**” functionality and the new “**Git Merge**” (v2). +- [**Merge (Legacy)**](#merge-legacy): The legacy merge uses a custom tool (originally built in FlutterFlow) to calculate differences and conflicts between branches. +- [**Git Merge (New)**](#git-merge-new): The new Git Merge option leverages Git's robust repository and conflict-resolution capabilities. + +:::warning + +At present, both methods are available side by side, allowing you to either continue using the legacy merge or adopt Git Merge. Over time, as Git Merge proves its stability, the Legacy Merge option may be deprecated. + +The Merge (Legacy) option has some known issues with merges being incorrectly calculated. Therefore, we **strongly recommend using [Git Merge](#git-merge-new)** whenever possible for a smoother and more accurate merge process. + +::: + +#### Merge (Legacy) + +You can initiate a merge in either direction—merging from a parent branch into a child branch or from a child branch back into the parent branch—by selecting the **Branch** Options button next to the current branch in the Branching Menu.
** select **Branching > Branching options >** select **Git Merge**. + +
+ +
+

+ + +When performing a Git merge in FlutterFlow, you’ll see a screen with multiple panels and info sections. Here are the details of it. + +![merging-window](imgs/merging-window.avif) + +**Top Panel** + +- **Branch Information**: At the top of the merge interface, you’ll see exactly which branches are being merged. You have two options for merging directions: + - **Parent → Child**: Pulls changes down from the parent into the child branch, often used to keep a feature branch in sync with the parent branch. + ![parent-child](imgs/parent-child.avif) + - **Child → Parent**: Pushes features (or other changes) from the child branch back up to the parent, commonly done once a feature is ready to go into the parent branch. + ![child-parent](imgs/child-parent.avif) +- **YAML Validation Errors**: These occur when the resulting data is not in a “FlutterFlow-friendly” format—whether that’s due to manual edits or merges that generate incompatible YAML. For example, imagine you have two pages in your project, and each branch independently deletes a different one. After merging, there are zero pages left. Even though no lines of code are edited or directly have a conflict, this results in a YAML Validation Error. Clicking on these errors should redirect you to the specific file. Invalid lines will be underlined in red within the file, and, you cannot complete the merge while YAML errors exist. +![yaml-validation-error](imgs/yaml-validation-error.avif) +- **Project Errors**: Project errors occur when the result of a merge creates a problem in your project. For example, this might happen if the merge results in two data types having the same name. These errors need to be resolved to ensure your project works as expected. You have several options to deal with project errors: + - **Fix Errors During the Merge**: This approach ensures that the merged project is error-free right from the start. Here’s how you can do it: + - **Edit the YAML files:** Update the project YAML files (in the Right Lower Panel) to fix issues, such as renaming a data type that causes a conflict. + +
+ +
+

+ + - **Edit the Project Directly while Merging:** While still in the merge process, open the project, make the necessary changes (like renaming the conflicting data type), and then continue. + - **Fix Errors After the Merge**: If you prefer, you can complete the merge first and address the errors later. For example, finish the merge process as it is. After merging, go back to the project and resolve any issues. +- **Cancel**: Abandons the merge process and discards any conflict resolutions you’ve already applied during this merge session. +- **Merge**: Finalizes the merge once all merge conflicts and YAML validation errors are cleared. Project errors can remain if you choose to resolve them later. +- **Bulk Accept Changes**: Accessible via the **arrow** next to **Merge** button. This option lets you accept all changes from one branch at once—handy if you already know which branch’s changes take precedence. +![bulk-accept](imgs/bulk-accept.avif) + +**Left Panel** + +The left-hand side panel displays all the project files in YAML format. YAML (Yet Another Markup Language) files use a simple, human-readable format to define configuration data. They are particularly useful during a merge because they allow you to directly review, understand, and resolve any changes or conflicts in your project’s file. + +- **Filter Files:** You can use filters to narrow down the list of YAML files based on specific criteria: + + - **All Files (Unchanged Files)**: Shows every YAML file in the project that has no changes. + - **Files with Changes**: Displays only files where a change has been made on either branch. + - **Files with Conflicts**: Shows only files that have merge conflicts, where the changes in one branch directly contradict the changes in the other. + + :::info + - A **change** refers to any update, addition, or deletion made in one of the branches. For example, modifying a field name or changing the properties of a widget. + ![change](imgs/change.avif) + - A **conflict** occurs when the same part of a file has been changed in both branches, making it unclear which version to keep. For instance, if one branch changes the color of the Container to blue and the other changes it to red, this creates a conflict. + ![conflict](imgs/conflict.avif) + ::: + +- **Search File:** If you’re looking for a particular file, you can use the search bar to locate it quickly. This is especially useful in larger projects with many files. + +Clicking on a file in the panel opens it in the editor, allowing you to view, edit, and resolve issues directly. + +**Right Upper Panel** + +The Upper Right Panel offers a quick, side-by-side comparison of file changes from both branches, along with easy one-click accept buttons and previews. This panel makes it simple to decide which changes to keep or discard. + +:::info +The edits are highlighted using green and red (Git) color coding: + +- **Green** indicates lines or values **added** (or unique) in one branch. +- **Red** indicates lines or values **removed** (or replaced) by that branch. +::: + +- **Accept Change Button**: Quickly accept changes from one branch if you know it has the correct edits. +- **Eye (Preview) Icon**: Open or view the file in the FlutterFlow builder to see how the changes look. For example, you can preview a theme color change visually rather than just reading its name in the file. + +**Right Lower Panel** + +The **Lower Panel** displays the final merged files after Git applies its merging logic. It gives you a chance to manually inspect and edit the outcome—whether or not a conflict occurs. + +Git attempts to combine changes from both branches automatically. If Git can’t reconcile certain lines, it flags a **merge conflict** in the file. Conflicts appear with special markers like `<<<<<<<`, `=======`, and `>>>>>>>`. + +- `<<<<<<<`: Marks the beginning of other branch’s changes +- `=======`: Separates your current branch’s changes from the other branch’s changes. +- `>>>>>>>`: Marks the end of the conflict, indicating your current branch’s changes. + +:::tip +You might decide to keep certain lines from `<<<<<<<` (from the other branch) or `>>>>>>>` (from your branch) or combine them manually. +::: + +You can modify files or edit the project directly from the lower panel at any time—even if there’s no conflict. + +After editing, click **Save Changes** to confirm your changes. A red reset button appears if you want to undo your changes and restore the file to its initial state before you began editing. + +### Resolve Merge Conflicts A merge conflict occurs when multiple team members make changes to the same part of the project. For example, imagine two developers, Alice and Bob, are working on the same FlutterFlow project and both decide to update the same button widget. @@ -236,6 +400,8 @@ When Alice's changes are merged into the main project first, her updates will be In your project, if you get merge conflicts, here’s how you resolve them. +#### Merge (Legacy) +
+ +
+

+ +Finally, complete the merge by clicking **Merge**. +:::tip +- If you merged a child branch into its parent and are confident everything looks correct, you may delete the child branch. +- If you find any issues after the merge, you can revert the branch to an earlier commit. However, be aware that any changes made after that commit will be lost. +::: + ## Branch-level Permissions In your project, you have the ability to assign specific roles such as **Editors** and **Mergers** to project members for each branch. @@ -361,4 +569,18 @@ Here’s how you can close a branch: - **Review before deletion:** Before closing a branch, ensure that all necessary changes have been merged or no longer need to be kept. - **Coordinate with your team:** If you’re working in a team, ensure that no one is actively using the branch before you close it, to avoid disrupting ongoing work. -::: \ No newline at end of file +::: + +## FAQs +
+ +How YAML files are helpful during a merge? + +

+YAML files play a key role in managing and resolving conflicts during the merge process because: +- YAML files hold important configuration data, such as settings, resource definitions, and project properties. During a merge, changes in these files reflect modifications to the structure or behavior of the project. +- The simple and hierarchical nature of YAML makes it easy to spot changes or conflicts, even in complex files. +- YAML files allow you to manually edit and resolve conflicts during the merge process. +- Since YAML files are text-based, they are version-controlled effectively, enabling multiple team members to make changes and merge their work. +

+
\ No newline at end of file diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/accept-all-from-one-branch.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/accept-all-from-one-branch.avif new file mode 100644 index 00000000..3d138ebf Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/accept-all-from-one-branch.avif differ diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/accept-specific-change-from-file.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/accept-specific-change-from-file.avif new file mode 100644 index 00000000..14e3f7b3 Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/accept-specific-change-from-file.avif differ diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/bulk-accept.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/bulk-accept.avif new file mode 100644 index 00000000..ee39ad79 Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/bulk-accept.avif differ diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/change.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/change.avif new file mode 100644 index 00000000..23bf6e99 Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/change.avif differ diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/child-parent.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/child-parent.avif new file mode 100644 index 00000000..b46cf576 Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/child-parent.avif differ diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/conflict.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/conflict.avif new file mode 100644 index 00000000..76eed82e Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/conflict.avif differ diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/merging-window.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/merging-window.avif new file mode 100644 index 00000000..c3c3813d Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/merging-window.avif differ diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/parent-child.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/parent-child.avif new file mode 100644 index 00000000..efeb43a3 Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/parent-child.avif differ diff --git a/docs/testing-deployment-publishing/branching-collaboration/imgs/yaml-validation-error.avif b/docs/testing-deployment-publishing/branching-collaboration/imgs/yaml-validation-error.avif new file mode 100644 index 00000000..c9b8e7b8 Binary files /dev/null and b/docs/testing-deployment-publishing/branching-collaboration/imgs/yaml-validation-error.avif differ