The Git branching model is a staple of the system and unique to Git alone. UEStudio includes full support for managing Git project branches via the Branch Manager dialog. This dialog can be accessed 2 different ways:
1. Via the ribbon: Project tab -> Git dropdown -> Show git branch
2. Via the Project pane's repository folder context menu: Git -> Branch manager…
If no project is opened, or if a project is opened but it does not contain any Git repositories, the buttons in the Branch Manager will be disabled and a message at the top of the dialog will indicate this.
The Git Branch Manager dialog includes the following options:
|
Control: |
Function: |
|
Repository |
The repository is a (non-editable) field indicating the full folder path to the active Git repository. If the current project includes more than one Git repository, a dropdown containing all repositories in the project will be displayed. Users may switch to and activate a different repository by selecting it in this dropdown. |
|
Current branch |
shows the HEAD branch name and the description of the last commit |
|
Status... |
presents the dockable Git Shell and populates it with current status of repository |
|
Commit changes |
stages and commits all changes to the repository |
|
Push... |
Only available if the active repository is linked to a remote branch, this will push the local version of the repository to its remote location |
|
Pull... |
Only available if the active repository is linked to a remote branch, this will pull the remote version of the repository into the local repository |
|
Other branches |
lists all available branches in the repository, including remote references. From here, users may select a branch to checkout, delete, merge, etc. |
|
Branch filter |
allows users to begin typing the name of a branch to filter the "Other branches" list to just those that match |
|
Refresh |
refreshes the list of available branches |
|
Add |
adds a new branch or remote reference |
|
Checkout |
checks out the selected branch in the "Other branches" list - disabled if nothing is selected |
|
Delete |
deletes the selected branch in the "Other branches" list - disabled if nothing is selected |
Branch list/Checkout
The full list of branches in your repository is shown in the "Other branches" table in the Branch Manager dialog. Remote branches (references / tracking branches) are indicated by the subdued text (medium gray in the screenshot above) in the listing. Branches that have been merged into your active branch are indicated by a checkmark next to the branch name. Users may switch branches (checkout) by selecting the branch they wish to switch to and clicking Checkout at the bottom-right of the list. Users may also double-click a branch in the listing to checkout / switch to that branch. If the branch is a remote branch, UEStudio will notify the user that a local branch and tracking branch must be created in order to check out the remote branch. When the checkout is complete, UEStudio will prompt the user regarding the new current branch, and the Branch Manager dialog will be updated to reflect this. The new current branch will also be reflected in the Project pane directly beneath the main repository folder.
Stashing
If a user tries to switch branches but still has uncommitted changes in the current branch, UEStudio will warn the user of this and ask if they would like to stash the changes before checking out the other branch. Stashing will leave the modified files of the current branch in a "modified/staged" state (indicated with an orange icon overlay). If the user chooses not to stash the changes, UEStudio will abort the checkout altogether. UEStudio will notify the user that the stash was successful. Users may can later reapply a stash by checking out the branch in which changes were stashed, right-clicking on the repository folder in the Project pane, and selecting Git -> Reapply stash.
Creating a new branch
Users may create a new branch, based on the active branch, by clicking the Add icon. This offers two options: New branch or New remote reference. If New branch is selected, a dialog will be shown where the user will enter the new branch's name and then click OK to create and switch to the new branch New remote reference may be selected to pull in branches from other users' repositories. In the resulting dialog, users will enter the remote reference name (for example, "github"), and the remote URL (for example, "https://github.com/user/repo.git"). UEStudio then issues the commands to create the new remote reference, and the new branches will be populated in the branch list.
Users may check out a remote branch if it has been pulled into the active repository, but must keep in mind that Git will maintain both a "tracking" branch and a corresponding working branch. When the user first attempts to checkout a remote branch, UEStudio will ask them to set up a local tracking branch for that purpose. Once this is confirmed, UEStudio will automatically switch to the new tracking branch.
Deleting branches
Users may delete a branch by selecting it in the list and clicking the Delete icon. UEStudio will confirm the deletion and prompt for credentials if authorization is required. The Delete button is disabled until a branch is selected in the branch list (deleting the active branch is not supported). It is possible to select multiple branches in the branch list via Ctrl + Click and delete them all at once. If the branch chosen for deletion contains commits that have not yet been merged into another branch (meaning, commits could be lost), UEStudio will display a warning to alert the user of this. The warning must be confirmed if the user wishes to continue to delete the branch.
Users may delete a remote branch by selecting it in the list and clicking the Delete icon. UEStudio will confirm the deletion first and prompt for credentials if authorization is required.
Merging branches
The Git merging model is designed so that users must first check out the branch they want to merge into then run merge command on the branch they want to merge from. UEStudio handles all merge operations within the Branch Manager. The active branch is shown in the box on the right. Users may click and drag the branch they want to merge onto the active branch from the branches list to the empty box on the left. When the user drops the branch onto the box, UEStudio will populate the box with the branch name and turn its border green to indicate that a valid branch has been selected. The user may then click the green Play button to run the Git merge. UEStudio will confirm the merge. UEStudio will run the merge in the background with output shown in the output window, and the merged branch will be updated with a checkmark in the branch list to indicate it is now included in the active branch.