Getting started with Git

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 SSL protocol via https. Therefore, there is no need to deposit an SSH key on OpenVT.

Cloning an OpenVT repository with https

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 https cloning (the link starts with https://).

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 https (recommended method), type

git clone <https_cloning_link>

(replace <https_cloning_link> with the link that you have copied from the blue button on the repository web site). You will be prompted for your OpenVT username and password, if the project you are about to clone requires any access privileges.

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.

If for some reason,

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 user name and password 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.