Skip to main content

Keep branches up to date with branch merging

Learn how to use branch merging and resolve merge conflicts when using Source Control.

From within the IDE of your app, module, workflow, or query, you can use branch merging to integrate changes from your default branch and resolve merge conflicts. While it's also possible to resolve conflicts through your source control provider's UI or the Git CLI, Retool recommends using the in-product branch merging, as it automatically checks for Toolscript validity.

Branch merging in Retool uses the git merge strategy. Read more in the git documentation.

Branch merging is currently rolling out in public beta on Retool Cloud and will be available on a subsequent edge version of Self-hosted Retool. Enable branch merging by navigating to Settings > Beta, and toggle on Enable branch merging.

Integrate changes from default branch

Branch merging is enabled when you are developing on a feature branch and have made a commit. When you're ready to update your branch, click the Merge main into <BranchName> button. Retool handles each of the following three scenarios:

  • Your branch is already up to date, and there are no changes to merge.
  • Your branch is out of date, and there are no conflicts between the default branch and your feature branch. Click Commit merge to update your branch.
  • Your branch is out of date, and the changes on the default branch conflict with those on your feature branch. View and resolve the merge conflict from within the IDE. Retool checks that the updated Toolscript is valid. Click Commit merge to update your branch. Refer to Toolscript-specific resolution strategies.

Toolscript-specific resolution strategies

Toolscript is available on Retool Cloud and self-hosted Retool versions 3.6.0 and later. See the migration guide to learn how to migrate your apps from YAML to Toolscript.

If your branch has conflicts with the default branch, you may need to edit Toolscript files. It is important to understand how Toolscript files are structured to resolve merge conflicts correctly. Malformed Toolscript files can result in failed Source Control deployments and prevent builders from pushing new commits.

Metadata files are located in app/.metadata.json. They hold metadata about the application, such as the Retool version the app was edited on and app-level settings.

If the conflict is in the version field, you should keep the later version number.

Most other fields in this file reference app-level settings. If two builders modify the same setting, keep only one valid change in the final commit. If two builders toggle different settings, it is safe to keep both settings.

Merge conflict prevention strategies

The development processes you use can help prevent merge conflicts from arising in the first place.

Keep branches and pull-requests short-lived

Trunk-based development best practices recommend branches are used for short-term feature work and kept open for a week or less. The faster a pull request is reviewed and merged into the main branch, the less likely it is for conflicting changes to be merged in during the same period of time.

Add test deployments to your CI pipeline

Test deployments allow you to programmatically validate a potential change to your Retool repository. You can add a test deployment check to you source control provider (GitHub, etc.) to prevent invalid changes from being merged.

Use modules to divide work

Retool modules are an excellent way to encapsulate a body of work, allowing one individual to develop on an isolated part of an app without affecting others. Before working on a complex app, it can be useful to plan what pieces of the app can be designed as reusable modules.

Assign different responsibilities to builders

Dividing responsibilities among builders helps ensure that builders make changes in different parts of the codebase. For example, you can assign one builder to work on the executable pieces of the app (e.g., queries and transformers), while another builder works on the visual pieces of the app (e.g., headers, titles, and images). Since the former exclusively affects files in the lib/ directory while the latter primarily affects files in the src/ directory, the chances of a conflict are minimal.