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#
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.