In this guide we will take a look at the 'Version Control' menu and all the associated functionalities that go along with it. This will include subjects like branches, merge requests and their flow of approval, the commit tree and looking up additional information for nodes if they have been part of a merge request in the past.
What is Version Control and where can I find it?
Version control allows you to keep different versions of your data in the same space by using different branches. What this will allow you to do is keep one of the branches as the accepted version of the data, while simultaneously working on the data on another branch without affecting the other branches. Then once you feel that all work has been done on one of the version you can compare the differences between branches and merge them so that the changes made on the branch you are merging will also be made to the branch you are merging into (more on this process in the merge request section of this guide). Alternatively, you can work on a single branch and use the different branches to make a backup of the data as it was.
During this guide we will refer to to version control menu from time to time, this menu is present on the taskbar located on the left side of the screen as can be seen in the screenshot below. Depending on the rights you have on a space, this menu will contain either 4 items if you have write access to a space, or 2 items if you only have read access to a space.
What are branches and how can I use them?
As mentioned in the introduction, branches are the key component in version control. In any space there will always be a Main branch that is selected by default, and unless specified otherwise, all imports will write the data to this branch. From this main branch, you can branch off and create new branches.
These branches have two possible configurations, they can be branched of another branch or they can be parentless. If they are branched from an existing branch, the new branch will be an exact copy of the existing branch, containing the same data. If the new branch is parentless, the new branch will contain no data at all.
To switch branches, we can access the branch menu in the bottom left corner as shown in the image below:
In this case we see that we are currently on the 'Main' branch, when clicking on the active branch name, a menu will appear containing all the other branches available on this space. In this case, a 'Develop' branch has also been made.
So where can you make new branches? To do this we will need to go to the version control menu as shown in the first picture of this guide. In this menu, click the menu subitem 'branches'. In this menu you will see an overview of the existing branches and several other buttons, these will be described in the sections below, but for now we'll focus on the button to create new branches.
Pressing this button will take you to the next menu where the branch will be created. This step contains two options, a mandatory field where you can name your branch and a dropdown menu where you can select where to create the branch from. By default this will be set to the Main branch, but any existing branch can be selected or you can choose to make a parentless branch as can be seen in the image below.
Pressing the 'Create branch' button will create the new branch.
We will now quickly look at the other options that we can see in the branches menu.
As you can see in this over view there are three labels that can be given to a branch, default, current branch and protected. Main will always be the default branch and cannot be changed. Current branch is an indicator on which branch you are currently working and will change when you switch branches as explained at the start of this section.
The last label is protected, this will protect a branch from being deleted through this menu. To set the protected status on a branch you can click on the three dot button next to the branch.
This will open a menu that allows you to protect a branch, unprotect a branch and delete a branch. Delete branch will not be clickable if a branch has the protected status.
Next up in this menu are the functions next to the New branch button that we used earlier.
The 'Filter branches' box allows you to search for branches and will filter out any branch that does not contain the search criteria. The checkbox on the far right allows you to select all unprotected branches at once and use the bin icon to mass delete them instead of using the three dot menu we saw above. Note that this bin button can also be used on branches you've selected manually (by marking the checkbox next to a branch) in the initial branch overview menu.
The last buttons in this branches menu are 'Merge request' and 'Compare' These can be used to compare and move around data between two branches. In the next section we will explain how transferring data from one branch to another works by making a merge request.
What are merge requests and how do I use them? (under construction)
- what are they
- where to find them
- how to make them
- approving and merging
- looking at old merge requests
- open merged and closed
What is the commit tree and what can I use it for?
The version control menu also contains an submenu 'Commit tree', this is where you can see a quick visual representation of all existing branches and any previous merges that have been performed in a space. An example of a commit tree is given in the image below:
Here we can see the main branch being represented as the black line on the right side, as indicated by the label at the top of the screen. We can also see a brown line representing the development branch. As you can see, the green line originated from the black line, meaning the develop branch was branched off from the main branch. There is also a purple line representing the parentless branch, this was not branched of any existing branch so its point of origin is not on any other branch.
In this image you also see a timeline on the side, and as you will notice, the top of the screen represents the latest point in time where any change was made to a branch.
Lastly we can see that the parentless branch was merged into the develop branch, this is indicated by a line going from the parentless branch up to the development branch.
Comparing branches and looking up merge requests (under construction)
As we have seen in the merge request section, one of the functionalities we use in merging is comparing branches. We can also use this function on its own if we just want to see the difference between branches without making merge request. This can be done in the fourth menu item in the 'Version control' menu.
Clicking this menu item will take you to the compare branches view, here two branches need to be selected in the same way we described in the merge request section.
- introduction
- looking for merge requests on nodes in the context menu
Config Branch
There is also a special branch available on each space, the '$config' branch. On this branch we store some data involving space settings, services and other space specific variables. Note that this branch is, by default, not visible. But should a user turned on the option to see it (through the data settings menu), this branch will be visible in all places mentioned.
By default, this branch is protected and can't be deleted. Merge requests to this branch are also not possible.