Work with Branches
Branching lets you work on different features and updates at any time without affecting the original source code.
This section helps you work with your Git branches in the context of the Designer.
Merge Remote Branches
Use the Merge Requests tool in VB Studio to merge remote branches, such as when you want to merge a remote branch with your changes into the main branch. Your team members can use the tool to review your changes, leave comments, and to approve or reject your merge request. If your request is rejected, you'll need to fix any problems and create a new merge request.
A merge request is created automatically when you use the Merge After Review option in the Publish Changes dialog box in the Designer. To publish the extension, you'll need to open the Merge Requests page in VB Studio and merge the branch into the main branch.
You can also create merge requests in the Merge Requests page. You'll need to create a merge request when you want to merge two remote branches. For details on how to create and work with merge requests, see Review Source Code with Merge Requests in Using Visual Builder Studio.
It's good practice to ask some project members to review your changes, but it isn’t mandatory to get approval from all reviewers before you merge the review branch. Note that you can’t merge the review branch if the target branch is locked. If it's locked you need to contact the project owner to unlock the target branch. For details on how to merge branches, see Merge Branches and Close the Merge Request in Using Visual Builder Studio.
To merge two remote branches:
When your merge is complete you'll see a summary of the merge request in the Conversation tab. If you didn't select Delete Branch in the Merge dialog box, you can delete it now by clicking Delete Branch. After merging a branch to the main branch, the branch is automatically closed and you can no longer use it. To make additional changes you'll need to create a new branch in your workspace or open an existing branch.
In the main Merge Requests page, you can see the status of merge requests in the table, and locate requests using the built-in filters, for example, Created By Me.
Cherry-Pick Commits Between Branches
You can cherry-pick commits when you want to apply a commit from one branch to another in your workspace. Typically, you'd cherry-pick commits from a remote branch to the working branch in your workspace.
Cherry-picking is useful when you work with multiple Git branches in a repository, either on your own or in a team environment. When you only need a specific commit from another branch, it's easier to cherry-pick that commit, instead of merging that entire branch to a remote repository. You can cherry-pick commits only between branches in the same repo.
Get the Revision ID of a Commit
Before you can cherry-pick a commit, you'll need the ID of the revision you want to include in your branch.
- If the commit is local to your workspace, follow these steps:
- If you or one of your teammates already pushed the commit to a remote
repository, follow these steps:
Cherry-Pick a Commit From Another Branch
Once you have a commit's revision ID, you can cherry-pick it to your working branch. Make sure you select the correct branch to cherry-pick the commit.
To cherry-pick a commit to your working branch:
Create or Switch a Branch
When you create an extension with a Git repository (instead of a scratch repo), VB Studio creates two branches in the repo: the default branch (usually, main
) and a working branch.
The main
branch contains the initial set of source files for the extension. The working branch contains the same set of source files initially, but as you work on your extension, this branch will contain the changes that you make. Using the Switch Branch/Sandbox option, you can commit your changes and then switch branches, or create a new branch from a parent branch that you select.
Note:
You don't have to switch to another workspace to configure another page in your App UI, as long as the target for your change is in your current Git repository. It's much faster to switch branches within a workspace than to switch workspaces. For example, suppose you're working in an extension (that is, a Git repo) for the Digital Sales App UI. Let's say you're configuring the Accounts page, but then get an urgent request to fix something on the Opportunity page and deploy it to your production instance. Rather than create a new workspace, you simply create a new branch, make the fix and publish it, then switch back to the Accounts page code line and resume your work.You use the Switch Branch/Sandbox dialog to switch branches or create a new branch from a parent branch that you select, or, optionally, switch from one sandbox to another.
Rename a Branch
When you want to rename a Git branch, you can use the Rename Branch option to change the name of your local branch, then push the renamed branch to the remote repository.
Note:
Exercise caution when renaming branches, especially if other team members are still using those branches. Renaming the default branch (main
, for example) might break build scripts that your repository uses. Before you rename the branch, you'll want to update references to the old branch name in your code or scripts.
Renaming a branch changes your current branch's name while keeping its history and pushes the renamed branch to remote, but the current remote branch is not renamed or deleted. Suppose your current branch is mybranch
and you want to change its name to newbranch
, the rename first replaces the local mybranch
with newbranch
, then pushes the local newbranch
to the remote repository. No changes are made to mybranch
, the previous existing remote branch. You'll have to manually delete this remote branch if you want to.
If the branch you want to rename is local (that is, it isn't tracking a remote branch), the branch is renamed, but isn't automatically pushed to the remote repository—the branch stays local even after the rename.
To rename a branch:
The renamed branch shows up in the header as your current branch.
Delete a Local Branch
You can delete a local Git branch that you no longer need to keep your workspace free of clutter. Typically, after your work on a branch is done and you've pushed your changes to a remote repository, it's good housekeeping to delete your local branch.
If your work required you to create a merge request, you can delete the branch immediately following the merge. For all other scenarios, you can use the Delete Local Branch option in the Git menu.
If you delete a branch that hasn't been pushed, its unique commits are likely to be lost. Make sure you push any commits you want to keep.
To delete a local branch:
Using Branches with a Sandbox
Within your workspace, you can use separate branches for changes you want to make for two different sandboxes, or for different versions of a feature that use the same sandbox.
For example, when modifying a table component in your extension, you might want to work on two different versions of the table. By creating a branch for each version, you can work on one version in one branch with Workspace A mapped to it, and then switch to another branch by using Workspace B to work on the other version. This way you can use your workspaces to help you isolate the branches with your changes. After you decide which version you want to use, you can share the branch with others and delete the branches you no longer need. See How Do Sandboxes Relate to Git Branches?.