How to work with the git repositories of the QC group

The LaTeX source files for the exercises to the lectures, for the instructions for lab courses and some other documents for our group are maintained with the help of git as revision control system, which provides support for recovering previous versions and/or merging changes made simultaneous by different persons, or, to be more precise, in different copies of the files.

Configuring git:
If you have never before worked with git in the computational environment you want to use now, then, before starting to actually work with git, you should set a few defaults (but using your own user name and email!): 

 git config --global user.name "Christof Haettig"
 git config --global user.email "christof.haettig@rub.de"
 git config --global core.excludefiles ~/.gitignore_global

  1. With the core.excludefiles options you set a file name (here ~/.gitignore_global) where you can define a number of directories, files, or file types that will be globally ignored by git. Gobally means here: with all git repositories to which you might work. It is recommended to specify in this file automatically generated backup files or directories that one typicall never wants to add to git. For example, put into this file the following lines: 
    *~ 
*.swp   
*.swo   
.DS_Store
*.aux
*.dvi
*.log
  2. Whenever you commit changes to git it will open an editor to enter a log message. By default git uses for this the editor you defined in your environment variable $VISUAL. If you want to use with git a different editor you can set it with 
     git config --global core.editory emacs


The git repositories on RUB Gitlab server

Server location:

  • gitlab.ruhr-uni-bochum.de

Repository organization:

  • LABCOURSES_AND_EXERCISES/*: problem and solutions sheets for excises, instructions and materials for lab courses
    (one git repository for each course, for old stuff one repository per semester & course)
  • PAPER/*: LaTeX sources for some of our own papers
    (Please generate one git repository for each paper)
  • NOTES/*: meant for notes about everything else
    (Please generate one git repository for each topic)
  • Python_fuer_Chemiker_und_Biochemiker/*: material for Bachelor courses in combination with Python
  • LECTURES/*: Lecture Notes
  • TURBOMOLE Code Docu/*: Some documentation for Code contributions in TURBOMOLE

Getting access:

  1. You need to have a valid RUB Login ID (user name and password for central RUB services)
  2. Use your RUB Login ID to sign to RUB GitLab
  3. Then ask Christof Hättig to get included as member to a gitlab repository or repository group. After you obtained access, you should find in the GitLab repository further instructions how to work with the repository.

Adding new repositories: If you got permission to add a new repository to a repository group on the GitLab server, you have two possibilities to add new repositories

  1. From an already existing (local) repository:
    1. Make sure that in your local repository all files that you want to be included have been committed.
    2. Then do the following (assuming that master is your default branch that you want to push):
      git remote add origin git@gitlab.ruhr-uni-bochum.de:path_for_repository_group/repository_name.git
      git push --set-upstream origin master       To to push other branches replace master by the name of the branch that you want to push to the repository on GitLab.
  2. From scratch:
    1. Enter on the GitLab server the repository group to which you want to add your repository.
    2. Click on the blue "New project" button.
    3. In the next step you need to select an option for creating a new project. Usually, you should select "Create blank project".
    4. Follow the instructions on GitLab.
    5. After having created the project on GitLab, you can clone it to a local directory, add, commit, and push your files.


The git repositories in the theochem file system

Repository location:

  • login:/home/turbomole/GITREPOSITORY/*/*

Repository organization:

  • PAPER/*: LaTeX sources for some of our own papers
    (Please generate one git repository for each paper)
  • NOTES/*: meant for notes about everything else
    (Please generate one git repository for each topic)
  • DOCU/*:
    (Please generate one git repository for each subject)
  • TEMPLATES: meant for templates for posters, presentations, papers, etc.
  • webpage.git: contains the webpages

How to work with an existing git repository:

  • For example, for the TC3 practical, create a clone of the repository under the directory you want to have it using
    'git clone ssh://username@name_of_your_local_machine.theochem.rub.de/home/turbomole/GITREPOSITORY/PRAKTIKA/IMOS-TC3'
    to download the source files into the subdirectory 'IMOS-TC3'.
    If you want to clone on a machine outside the theochem network and you have on this machine several ssh keys it might be neccessary to tell git which key should be used to access our git repository with
    'git clone -c "core.sshCommand=ssh -i ~/.ssh/my_key_for_login -F /dev/null" ssh://username@name_of_your_local_machine.theochem.rub.de/home/turbomole/GITREPOSITORY/PRAKTIKA/IMOS-TC3'
    (all in one line)
  • After making changes in the files you wanted to modify use the commands to commit the changes to your local repository:
    git add [file names]
    git commit
  • To push to the changes to the central clone use:
    git push

How to create a new git repository (within this directory tree):

  • Use the usual commands and programs to create on your local machine a directory with initial versions of some of the files that you want to upload.
  • Go into this directory and enter the commands:
    git init --shared=group
    git add [file names]
    git commit
  • Login to a theochem machine, go in the /home/turbomole/GITREPOSITORY directory tree to the folder in which you want to create the central clone of your git repository and issue the command:
    git init --bare --shared=group [directory name]
    Note that "group" is an actual keyword and is not supposed to be replaced with the actual name of the group.
    Make sure that the directory and its content is group writeable: chmod -R ug+rw [directory name]
  • Connect your local directory with the central clone and push it's content:
    git remote add origin ssh://username@name_of_your_local_machine.theochem.rub.de/home/turbomole/GITREPOSITORY/[subdirectory]/[directory name]
    git push -u origin master
  • From now on you can work as usual with git in your directory. Please, add a .gitignore file with the names of the file that should be ignored by git (e.g. *.log, *.aux, etc.). Typically all files that can be generated from uploaded source files should be ignored by git.