GitLab

Subtrees allow linking repositories in a nested way. Compared to submodules, subtrees come with the advantage that it also works with https and that cloning the main repository automatically also clones the content of the subtrees. On the other hand, the git commands using subtrees tend to be lengthy.

In the following, a few hints how to get started with subtrees and how to perform simple subtree operations -- for more information, please refer to the Gitlab documentation.

In case you prefer working with submodules instead, please check out the Submodule section. However, note that a submodule structure might not support pulling/pushing via SSL.

Cloning a repository with Subtrees

If you would like to clone a project containing a subtree, there is nothing special to do -- cloning the project automatically also clones the content of the subtree.

Creating a Subtree

In case you would like to include a subtree into one of your projects -- e.g., you would like to include the vivaplus HBM into a project called my_project -- you have to create a subtree first. Browse into a folder on your computer containing a clone of my_project and do the following:

git subtree add --prefix vivaplus <cloning_link_vivaplus> <branch_name> --squash

This creates a subtree containing the branch <branch_name> in a folder called vivaplus (you can also change that name, just add the desired name after --prefix). The branch name is probably in most cases master -- but you can also use any other existing branch, or even a certain commit hash if you would like to point to a given commit. The option --squash only copies the latest version of the branch, without the history (if you leave it out, it comes with history, which makes the folder larger).

Pulling and pushing to/from Subtrees

The content of the Subtree is essentially a copy of all contents of the linked repository, but without the history. In case there were updates on the repository, you might want to update the subtree. That is done with pulling, just like you would do on a local clone of a repository, just the command is a little bit more complicated - in the example above, the syntax would be:

git subtree pull --prefix vivaplus <cloning_link_vivaplus> <branch_name> 

Pushing works in the same way, just replace 'pull' by 'push.' That means, you can also push you changes to the linked repository back through the subtree. Of course, you can only push to a repository and branch that you have permissions to push to.