Using git#

Git is the most popular version control system, used in our group for sharing code and manuscripts.

A simple introduction to git can be found over here: http://rogerdudler.github.io/git-guide/

To get a feel for all the git commands, also check out the interactive tutorial at https://learngitbranching.js.org/

All the git repositories of the group can be accessed at http://gitlab.kwant-project.org/qt

In order to get access, create an account at gitlab and inform Michael or Anton.

When setting up an account create an ssh key and upload the public key to your account. You can then access the repositories from the computer(s) having the private key.

Don’t forget to specify your name and email in git settings. To do that run:

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

It’s best to choose the same email as specified in your gitlab account information.

Don’t do git pull#

Always do

git pull --rebase

or even better set it in your git config (this setting makes every pull also a rebase):

git config --global branch.autosetuprebase always

Explanation#

In times of intensive works people are pushing to repo very often and in many cases you will find your repo behind origin. When you just type git pull git will want to merge your local repo with origin. To avoid that and keep everything clean always use ‘’git pull –rebase’’ or change your git settings to always use ‘’rebase’’ feature.

Avoid merging#

However if your habits are stronger than you expect, and you don’t want to change your settings, you can always abort merging initiated after ‘’git pull’’. To do it simply exit editing of new commit message with ‘’ctrl + x’’ and do

git reset –hard HEAD^ git pull –rebase

Git for latex#

You can very easily produce compiled manuscripts with redlined changes by using http://tex.stackexchange.com/questions/1325/using-latexdiff-with-git

Repositories on your own#

If you want to share your work with someone else, you can just create a private repository on gitlab. Afterwards if you want to move it to the group, ask Anton or Michael.

You also create a bare repository on any computer to which you have access like this:

git init --bare path/to/your/new/repo/name.git

To start using it go to your desktop machine (or other folder on ‘’hpc1’’) and clone your repo with

git clone host:path/to/your/new/repo/name.git 

<note important>Don’t share repositories over dropbox: simultaneous edits will destroy the history and everything you value and love.</note>

Commits and commit messages#

  • Avoid making a generic commit message. “minor style improvements” or “typo fix” are much better than “edit”.

  • Don’t mention the filenames involved: git tracks the files anyway.

  • Make a short one line description (that way it’s easy to read in the log).

  • If you need a longer explanation, add a line break after the short description and make the long one.

Managing data in repositories#

In general avoid pushing large data files to a repository unless you are certain the data is needed for the project. In that case it is recommended to make a separate data repository and add it as a submodule to the original repository using

git submodule add "your_data_repository"

If you still end up with large unwanted data, use BFG-repo-cleaner to remove the unwanted data.

First install using

mamba install -y openjdk && wget https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar

Then follow the instructions as on the BFG-repo-cleaner website

Use du -sh * to check if the cloned repository total data has decreased

If so use git push --force to push back to the repository. Make sure forced push is possible for the repository first.

Finally, ask Anton to do some garbage cleaning in your repository.