Git Branches

Git branches are a good way to handle contributions of several developers, where some are working on new, maybe somewhat experimental parts of the content, while the established part of the content is protected from being ``messed up'' by premature or erroneous contributions.

By default, every repository has at least one branch, which is called Master. If no other branch exists, any commits and pushes always alter the Master branch, while Git remembers the complete version history of this branch.

If a new branch is created, the version history bifurcates at this point and is being kept separately for Master and the new branch. Users can synchronize local clones with either of them (this process is called checkout) and can commit and push to one or the other (provided that they have permission to push to the Master branch -- the project owner can restrict the permission to that). At a later stage, if it turns out that the content of the new branch is useful, it can be re-included into the Master branch -- this is called Merging.

Creating a new branch

In the following, we assume that you have access to a repository called MyProject on OpenVT, which you have readily cloned to your computer. Open a terminal and browse into the respective folder. In order to make sure to have the latest version of the content, do a

git pull

Now, we will create a branch called MyBranch:

git branch MyBranch

This will now be created both locally (in your clone) and on the remote repository - also called origin. You can choose the branch that you are working on by doing

git checkout <branch_name>

where branch_name could be master or MyBranch in our case. If you check out MyBranch, you can do any modifications to its content as usual. When appropriate, you can push your modifications to the remote repository by doing the usual steps

git add .
git commit -m 'commit message'
git push origin MyBranch

The last line tells git to push the changes to the remote version (origin) of MyBranch. Similarly, if you pull while MyBranch is checked out, the remote status of MyBranch will be pulled instead of master.

In case you have forgotten on which branch you are or you would like to know about not yet pushed commits or changes yet to track or commit, the command

git status

will tell you all that.

Merging branches

In many cases, after having successfully modified the branch and tested the modifications, you might want to re-include the modifications into the master branch. This process is called merging and Git helps you to do it flawlessly and as automatically as possible, no matter how many modifications have been done on either of the branches in the mean time.

So, let's say, you did some modifications in MyBranch, e.g., you have added a file my_file, which is not present on master. You have added, committed and pushed it. Now, you check out master and merge:

git checkout master
git merge MyBranch

This will automatically create a commit on master, where my_file appears also on master. Please note that this only appears on your local version of master so far. If the merge went well, you have to

git push origin master

again in order to update origin (i.e., the remote version of the repository).

Now this was obviously an easy example, as the only change was an additional file and master did not change in the mean time. It gets more complicated, if e.g. you are modifying a file present in master, which another user has changed in the mean time. But even this will in may cases be handled automatically by Git, if you happen to have changed different lines of the file. If you have actually committed conflicting changes, this will be shown in the files that are concerned; you have to solve the conflict manually, then add, commit and merge again.

If you are experiencing trouble with more complex merges, please always ask the owner of the respective repository. If you happen to be the owner, contact the platform admins via the issue tracking board.

Submodules

Submodules are a handy tool to include other Git repositories (either on OpenVT or on other platforms) as a folder structure into your own repository. On OpenVT, this is used e.g. to include the PIPER child model repository located on Gitlab.com.

Please, find more information on that on the dedicated page.

Further reading about Git:

For any further information about Git, please refer to the git documentation on https://git-scm.com/docs.