GitLab

Git

Git provides a highly efficient open source version control system allowing a synchronisation of a repository with several remote copies (clones), which can be modified simultaneously by different users. Git is the core component of Gitlab and thus of the OpenVT platform.

Both Git and Gitlab are extensively documented, please refer to the help section for further reading. In the following, you find a very short getting-started introduction for new users of the OpenVT platform.

Installing Git on Linux and Windows

If you are using Linux, continue reading here. As a Windows user, continue here.

Configuring Git

You should have now a working installation of Git on your system. Next, you have to configure Git. We recommend a global configuration according to your sign-up data on OpenVT - if you are using other Git servers in parallel, you have to do local configurations for each repository (if that ist the case, you probably now how to do that).

Open a Terminal (as Linux user) or open the Git Bash app (on Windows). Type the following, where you replace <your_email> and <your_username> with the data you are signed up with on OpenVT:

git config --global user.name <your_username>
git config --global user.email <your_email>

Now, test the settings with

git config --global --list

and you should be shown a list with the parameters set above.

Creating an SSH key

The default way for secure Git operation on OpenVT is the SSH protocol. Therefore, before you can start creating local clones of OpenVT repositories, you have to create your own SSH key and deposit it on the platform. It is possible to use most of the git functionalities also via SSL: if you would like to use this method, you can skip the following steps.

Before generating and depositing an SSH key, make sure your git configuration is correct (see above). A key generated with a wrong configuration will not work.

Open a terminal (as Linux user) or open the Git Bash app (on Windows). Now, follow the instructions here. Use if possible ED25519 keys; in case that does not work, use RSA instead. During the creation, you will be asked to specify a passphrase: please, remember that phrase, it will be your access to secure Git actions later.

Now, you have to deposit your SSH key to your OpenVT profile. First, open the public key in a text editor, select everything and copy (alternatively, use a dedicated command, see here). Then, click on your avatar in the upper right corner and selecting Settings. From there on, navigate to SSH Keys and paste your public key in the "Key" section. If you created the key with a comment, this will appear under "Title". If not, give your key an identifiable title like Work Laptop or Home Workstation, and click Add key. Your key should now be deposited on your OpenVT profile.

Your can test your SSH setup with

ssh -T git@virtual.openVT.eu

If everything is set up correctly, you will be prompted for your passphrase and get a welcome message if you type the correct passphrase.

Cloning an OpenVT repository with SSH/SSL

Now we need to create your first local clone of a Gitlab repository. First, pick a repository on the OpenVT platform that you would like to clone (as a test, you can use the manual_and_guidelines repository, or just start your own private project). Browse to the corresponding repository screen (e.g., this one), find the blue "clone" button and copy the link for SSH cloning (the link starts with git@virtual.openvt.eu).

Open a terminal (on Linux) or the Git Bash app (on Windows) and browse to the directory where you would like to place the local clone. Type on the command line prompt:

cd <path_to_clone_directory>

where you replace <path_to_clone_directory> with the path to the directory where you would like to place the clone. Note that the path has to be specified Unix style (i.e., with / instead of \ as delimiter). If you would like to create a new directory, type

mkdir <name_of_new_directory> 

where you replace <name_of_new_directory> with the name of the directory to create, and again browse into to that directory using cd.

Now, the actual cloning can happen: If you would like to use SSH (recommended method), type

git clone <SSH_cloning_link>

(replace <SSH_cloning_link> with the link that you have copied from the blue button on the repository web site). You should be prompted to enter the pass phrase of your SSH key which you have (hopefully) memorised earlier. If you prefer cloning via SSL, type instead

git clone <SSL_cloning_link>

You will be prompted for your OpenVT username and password, if the project you are about to clone requires any access privileges.

If in either case the process was successful, the clone of the repository should appear in the current directory, which you can check by typing

ls -l -tr 

which shows you a list of all files and subdirectories in that directory in reverse time order. The clone should be shown as directory on the bottom of the list with the same as the cloned Project. You can now work with these files in this folder like with any other file on your computer.

Working with a cloned repository: pull and push

The basic actions for working with a clone of an OpenVT repository are pulling and pushing. Before doing any changes on the files in your clone, you should perform a pull, which updates the local copies of the files to the latest status on the OpenVT platform. On a command line (Linux terminal or the Git Bash app on Windows), cd into the clone folder and type

git pull

You will be prompted for your pass phrase and the files will be updated. Now, you can modify, add or remove files (using any command line or GUI tool of your choice). Once you are done, you have to commit your changes. In order to do that, use the command line again to cd into the clone directory and perform the following steps:

git add .

this adds new files or removes obsolete files in case you have added or deleted files.

git commit -m 'commit_message'

where you replace commit message with a meaningful description of the modifications you did. If you skip the -m option, git will prompt you for a commit message (for every commit, a commit message is required - use it in a meaningful way to inform other users about what you have changed).

git push origin master

this will prompt you for your pass phrase (or user name and password, for SSL) and upload your changes to OpenVT. If there is only one branch in your repository, you can skip the "origin master" options. On the other hand, if there are different branches, you can replace "master" with the branch to which you would like to push. Your modifications will now be accessible on OpenVT to anyone who has access to the project under consideration.

Repeat this work flow every time that you would like to do modifications on the contents of your OpenVT repository.

Next steps

Learn more about Git, about how to use branches and submodules, on the page Next steps with Git.

Further questions:

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