Branches

If you've followed the Getting Started section so far and published your first changes, we're very proud of you! 🎉 Now it's time to iterate by creating some more branches to add more features 👏

In this tutorial, you’ll learn how to create new branches, how to work on multiple branches, possibly with multiple people on the same project at once, and finally how to publish your changes.

Creating a new branch

When you create a new project, toddle will automatically create a branch for you called "start". If you've followed the intro tutorial, you may have already published the start branch , leaving you utterly branchless 😞 Fear not, you can always create a new branch, and you can even have multiple branches open at the same time!

Branches are like branches on a tree. Your trunk is what the end user sees, and when you create a new branch it grows from the trunk. At some point, when you have fixed your bug or finished your new feature, you may be ready to merge your changes back into the trunk, which leaves the branch completed and now part of the trunk.

Editing a branch

You can open and view the live version in the editor, but you cannot edit. To edit, you must create a new branch. With separate branches for individual features or fixes, you gain several advantages:

• Isolated Development : Each branch serves as an isolated environment for a specific feature or fix. This separation means that developers can work on their tasks without impacting the work of others.
• Easier Collaboration and Coordination : When each developer works on their branch, it reduces the need for constant communication and coordination that would be necessary if everyone were editing the same branch. This setup streamlines the development process and minimizes disruptions.
• Stability of the Live Branch : The live branch (or 'trunk' of the tree) remains stable, as it only contains completed and tested features.
• Simplified Testing and Debugging : Testing and debugging become more manageable when changes are isolated in separate branches. Developers can test their changes independently before publishing them, reducing the likelihood of introducing bugs.
• Reduced Risk of Conflicts : Separate branches reduce the risk of conflicts that can arise from simultaneous edits to the same part of the code in a single branch.

Merging a branch

Tip: Keep branches small and short-lived. Ultimately, a branch should contain just a single feature like "add-color-picker" or "fix-dialog-styling-issue". If the feature is too large, try to divide it up in smaller parts so that each branch can be closed within a single days work. This will help you iterate faster, avoid merge-conflicts, easier reverts and to better keep track of changes.

When you publish your branch, all of your changes are merged back into the trunk of the tree and will immediately be live on your site.

However, you may not be able to publish your changes, unless your branch is completely up-to-date with the latest published changes. If someone else has published some changes since you created your branch, you must first merge the newest version back into your branch. This way your branch sits right on top of the trunk and once you merge, the trunk simply grows a bit.

Conflicts

Merging changes into your branch is usually as easy as the click of a button (" sync with main " button). However, you may run into merge conflicts from time to time. This means that you have been editing the same component/page that was changed on the "main" branch and toddle is unable to determine how these changes should be merged together. Currently, you will need to reset/undo your local change before you can continue. If your change is important, we encourage you to copy those changes on to a new branch to avoid losing your work.

Previewing a branch

You can preview branches while you work on them. You can even send the preview link to someone else to test your changes before you publish. Previewing will take you to a URL `branch-project.toddle.dev`. Keep in mind that the preview is not as optimized as your live version, so these are not for production-use.

Time travel

Oh no! Someone published a serious bug, and now your users are going all bananas 🙈 Instead of panicking after a hotfix and potentially making things even worse, you can always just hit that "Rollback" button on a version you know worked. This will reset your live version to that exact state. This gives you time to find a solution while everyone is happy 👏