The source of this document is available on gitlab.
Last version: 2020-04-14

Git and GitLab

This document is particularly important if you follow the RStudio or the Org-Mode path. If you follow the Jupyter path, it can be ignored at first as we have closely integrated Jupyter and GitLab in the context of this MOOC.

So far, you only used git via the web interface from the GitLab we deployed for the MOOC: https://app-learninglab.inria.fr/gitlab/

If you access this link from the FUN platform, you do not have to authenticate and you can readily read and modify all your files. This is very convenient but in most cases, you will want to have your own local copy of the repository and you will have to synchronize your local copy with the remote GitLab one. To propagate your modifications, you will obviously have to authenticate yourself on GitLab.

This document describes the software you need to have installed on your machine and how to handle authentication. The "Configuring Git" section is illustrated in a video tutorial (in French).

Please read all these instructions carefully, in particular the one on "Configuring your password on GitLab".

Table of Contents

Installing Git

Linux (Debian, Ubuntu)

We provide here only instructions for Debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g., RedHat, Fedora).

Run (as root):

apt-get update ; apt-get install git

Mac OSX and Windows

Configuring Git

Telling Git who you are: Name and Email

  1. Open terminal.

  2. Set a Git username and email:

    git config --global user.name "Mona Lisa"
    git config --global user.email "email@example.com"
    

    These two steps are really important to commit. If you forget to do so, you will get the following message:

  3. Confirm that you have set the Git username correctly:

    git config --global user.name
    git config --global user.email
    
    Mona Lisa
    email@example.com
    

Dealing with proxies

You may be behind a proxy, in which case you may have trouble cloning or fetching from a remote repository or you may get an error like unable to access ... Couldn't resolve host ...

In such case, consider something like this:

git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port

The proxyPassword will be stored in plain text (unencrypted) in your .gitconfig file, which you may not want. In that case, remove it from the URL and you will be prompted for it every time it is needed.

To stop using a proxy, simply use the following command:

git config --global --unset http.proxy

Getting your default password on GitLab (and possibly changing it)

Warning (Jupyter users) : changing your default Gitlab password will prevent you from committing in Jupyter. You will have to do the extra step of changing your ~/.git-credentials in the Jupyter environment (possibly several times).

  1. Get your default password using the Gitlab credentials retrieval tool as described on the corresponding resource.

    The first long and ugly character sequence is your GitLab login/id. It is easy to find once you are logged on gitlab. The second one however is your password and this webpage is the only place where you can find it. We used the FUN authentification mechanism to propagate your credentials so only you can have access to it. You'll need to use this password when trying to propagate some modifications from your computer to GitLab.

    Note: You have to access this webpage from the FUN platform otherwise you may get a 405 error when trying to direcly open https://app-learninglab.inria.fr/jupyterhub/services/password.

  2. Access GitLab from the FUN plateform (click on "Accédez à Gitlab / Access to Gitlab" Button).

    Note: Again, you have to access Gitlab from the FUN platform otherwise you may get a 405 error /when trying to direcly open https://app-learninglab.inria.fr/gitlab/users/sign_in/.

  3. Click on the first Sign in button (alternatively, you can the login/password you just retrieved and use the second Sign in button).

  4. If you wish to modify your password, you should go to Account > Settings > Password and define your password using the default password you just retrieved. Again, if you use the Jupyter notebooks we have deployed for the MOOC, remember that changing your default Gitlab password will prevent you from committing in Jupyter. You will have to do the extra step of changing your Jupyter ~/.git-credentials through a Jupyter console (see next section).

Remembering your password locally

If you clone your repository by simply pasting the GitLab URL, you will be prompted for your login and your password every time you want to propagate your local modifications, which is tedious. This is why you should ask git to remember your login and password as follows

git config --global credential.helper cache                  # remember my password
git config --global credential.helper "cache --timeout=3600" # for one hour at most

With this setup, you will be prompted for your password but it will be cached in memory and they will not be asked again before an hour. You may want to read these instructions to better understand how all this works.

If you want your password to be permanently remembered, you should use this command

git config credential.helper store

Your password will be then stored in a .git-credentials file in plain text. On a perfectly secured machine, it may be fine… or not… ;) Use it at your own risk.

To delete all the passwords that may have been stored, simply use the following command:

git config --system --unset credential.helper

Finally, those of you using Windows may get the following error message:

git: 'credential-cache' is not a git command. See 'get --help'.

This issue is mentioned on stackoverflow. In such case, try the following command:

git config --global --unset credential.helper

If the problem persists, do not hesitate to describe your problem on the MOOC forum to get some help.

Optional: authenticating through SSH

There are two ways of authenticating and synchronizing your local repository with GitLab: through HTTPS or through SSH. The first one is what was just described and does not require any particular software installation on your machine so this is what I recommend for this MOOC. Yet, I like the second one better (although is may seem a bit more technical), which is why I describe it here. It consists in installing SSH, creating a pair or private/public keys, and uploading your SSH public key on GitLab. This section provides with information on how to do this.

Installing SSH

  1. Linux (Debian, Ubuntu)

    We provide here only instructions for debian-based distributions. Feel free to contribute to this document to provide up-to-date information for other distributions (e.g., RedHat, Fedora).

    Run (as root):

  2. macOS

    You do not have anything to do as it is installed by default.

  3. Windows

    You should install the Putty client. Once it is installed, look for the section on generating an SSH key.

Setting up SSH on GitLab

Here are all the official explanations on how to set up your SSH key on GitLab. Alternatively, you may also want to have a look at this video:

Using Git through the command line to synchronize your local files with Gitlab

This section describes a generic (through the command line) way to synchronize your local files with Gitlab. You will not need this if you follow the Jupyter path. If you follow the RStudio path, all these operations can be done through RStudio and you may want to read the corresponding instructions. If you follow the Org-Mode path, all these operations can be done through Magit and you may want to read the corresponding instructions.

Here are other ways to learn Git through the command line:

Now, let's start!

  1. Obtain the repository URL

  2. Cloning the repository

    cd /the/directory/where/you/want/to/clone/your/repository
    git clone https://app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git
    

    Alternatively, you may want to indicate now your login although I rather suggest you follow the Remembering your password locally instructions:

    git clone https://xxx@app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git
    

    Now a directory mooc-rr has been created on your computer.

  3. Inspect the repository

    cd mooc-rr
    ls # (Unix)
    dir # (Windows)
    
  4. Synchronizing to GitLab

    You should indicate which files to track (git add) and commit them locally (git commit) before they can be transfered (git push) to GitLab. The git status will indicate you whether files are tracked/modified/committed/…

    Let's assume you just created a fichier.txt file on the top of the mooc-rr directory.

    git status
    

    git add fichier.txt
    git status
    

    git commit -m "message commit"
    

    git status
    

    The file can then be transfered to GitLab:

    git push
    

    At this point, git will ask you about your login/password unless you followed the previous Remembering your password locally instructions.

    N.B.: you will not be allowed to propagate your modifications to GitLab if other modifications (e.g., from someone else) have been propagated in between

  5. Synchronizing from Gitlab: to avoid the previous problem, you need to fetch the remote GitLab modifications first and apply them locally.

    git pull
    

    Only then will you be able to git push.