Keep branches up to date with branch merging

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

Classic apps

You're viewing documentation for classic apps, which use Retool's original app editor. The new app builder is the recommended way to build apps and where Retool focuses new development.

From within the IDE of your classic 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.

note

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

note

Toolscript is available to cloud instances and self-hosted instances on 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

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.

Positions files

Positions files are located in app/.positions.json. They encode information about the visual properties for each plugin (e.g., positioning on the canvas).

In this file, each JSON key corresponds to a component's name. As such, all JSON keys must be unique.

Common causes

There are generally three causes for conflicts in this file.

Two builders repositioned the same components

<<<<<<< HEAD
"button1": { "row": 0, "col": 0, "height": 1 },
=======
"button1": { "row": 99, "col": 99, "height": 1 },
>>>>>>> main

In this case, each block in the conflict has the same JSON key. To maintain the component’s position in your branch, keep your block. Otherwise, keep the block from the main branch.

Two builders positioned components at the same location

Both changes modified the same location in .positions.json.

<<<<<<< HEAD
"button1": { "row": 0, "col": 0, "height": 1 },
=======
"table1": { "row": 99, "col": 99, "height": 1 },
>>>>>>> main

In this case, it is safe to keep both blocks.

If both of these causes happen (e.g., two builders repositioned the same components and added different components at the same location), review each conflict area and decide which strategy to apply. The .positions.json file is sorted alphabetically by key to help you identify duplicate entries.

App code

App code is located in app/main.rsx and app/src/*.rsx. These files contain the Retool components in the app and the app’s overall structure.

Common causes

There are generally three causes of conflicts in app source code.

Two builders edited the same component

In this case, you must only keep the “correct” changes.

Two builders added new components at the same location

In this case, it is safe to keep changes from both blocks, but you should pay attention to ordering. See order of components in app conflicts.

Order of components in app conflicts

When resolving app conflicts, you must carefully consider where your changes should end up in the Toolscript file. The order of components is important, as it helps determine visual placement of the component on the Retool canvas.

In general, your changes can go before, after, or within the other builder’s changes. In the last case, if the other builder introduced an import statement, you might have to place your changes in a different file entirely.

In this example, your changes should go after the existing changes.

// conflict
<<<<<<< HEAD
<Text id="message" value="hello world" />
=======
<Text id="title" value="My App" />
>>>>>>> main

// after resolution
<Text id="title" value="My App" />
<Text id="message" value="hello world" />

In this example, your changes should go within the existing changes.

// conflict
<<<<<<< HEAD
<Text id="message" value="Oh say can you see, by the dawn's early light" />
=======
<Container
  id="container1"
  showBody={true}
  showHeader={true}
  >
    <Header/>
    <View id="90751" >
      <Text id="content" value="You can find the lyrics below:" />
    </View>
</Container>
>>>>>>> main

// after resolution
<Container
  id="container1"
  showBody={true}
  showHeader={true}
  >
    <Header/>
    <View id="90751" >
      <Text id="content" value="You can find the lyrics below:" />
      <Text id="message" value="Oh say can you see, by the dawn's early light" />
    </View>
</Container>

In this example, your changes should go within a different file because another builder added an import statement.

// conflict - main.rsx
<<<<<<< HEAD
<Text id="message" value="Oh say can you see, by the dawn's early light" />
=======
<Import src="./src/container.rsx" />
>>>>>>> main

// conflict - container.rsx
<Container
  id="container1"
  showBody={true}
  showHeader={true}
  >
    <Header/>
    <View id="90751" >
      <Text id="content" value="You can find the lyrics below:" />
    </View>
</Container>

// after resolution - main.rsx
<Import src="./src/container.rsx" />

// after resolution - container.rsx
<Container
  id="container1"
  showBody={true}
  showHeader={true}
  >
    <Header/>
    <View id="90751" >
      <Text id="content" value="You can find the lyrics below:" />
    </View>
</Container>

Library code

Library code is found in the lib directory. It contains user-written executable code, such as JS and SQL files. These are most often used in queries, transformers, and certain code-first components.

Since this code is entirely user-written, there is no Toolscript-specific reasoning or advice for merge conflicts in these files. You may find the section on merge conflict prevention strategies useful.

Merge conflict prevention strategies

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

Keep branches short-lived

Keep a branch open for a week or less, and merge as soon as review completes. The longer a branch stays open, the more changes land on main behind it, and the more likely a conflict becomes.

Add test deployments to your CI pipeline

A test deployment validates a change against your Retool instance before it merges. Adding it as a required check in GitHub or your SCM provider stops invalid changes from reaching main.

Divide work so builders don't collide

Two builders editing the same app on separate branches will conflict. Two builders editing different parts of it usually won't.

• Use modules to encapsulate work. A module is an isolated part of an app that one person can develop without affecting others. Before starting a complex app, plan which pieces should be modules.
• Split responsibilities by file area. Assigning one builder the executable pieces such as queries and transformers and another the visual pieces such as headers, titles, and images keeps them in different directories, since the former affects lib/ and the latter mostly src/.