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.
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
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:
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 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 lione 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 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. If you would like to learn more about git and how to use more advanced actions such as branching and merging, please refer to the git documentation on https://git-scm.com/docs.