diff --git a/module2/ressources/gitlab_fr.org b/module2/ressources/gitlab_fr.org new file mode 100644 index 0000000000000000000000000000000000000000..19d60c3451e3070a81fd909be44200573fcddd65 --- /dev/null +++ b/module2/ressources/gitlab_fr.org @@ -0,0 +1,316 @@ +# -*- mode: org -*- +#+TITLE: Git et GitLab +#+AUTHOR: Arnaud Legrand +#+DATE: June, 2018 +#+STARTUP: overview indent +#+OPTIONS: num:nil toc:t +#+PROPERTY: header-args :eval never-export + +*Ce document est particulièrement important si vous suivez le parcours +RStudio ou Org-Mode. Vous pouvez l’ignorer dans un premier temps si* +*vous suivez le parcours Jupyter car nous avons étroitement intégré +Jupyter et GitLab dans le contexte de ce MOOC.* + +Jusqu'à présent, vous avez utilisé Git uniquement via l'interface web +du GitLab que nous avons déployée pour le MOOC : +[[https://app-learninglab.inria.fr/gitlab/][https://app-learninglab.inria.fr/gitlab/]] + +Si vous accédez à ce lien depuis la plate-forme FUN, vous n'avez pas à +vous authentifier et vous pouvez facilement lire et modifier tous vos +fichiers. C'est très pratique, mais dans la plupart des cas, vous +voudrez avoir votre propre copie locale du référentiel et vous devrez +synchroniser votre copie locale avec celle de GitLab. Vous devrez +évidemment vous authentifier sur GitLab pour propager vos modifications. + +Ce document décrit le logiciel que vous devez installer sur votre +ordinateur et comment gérer l'authentification. La section +"Configuration de Git" est illustrée dans un [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/7508aece244548349424dfd61ee3ba85][tutoriel vidéo]] (en +français). + +Veuillez lire attentivement toutes ces instructions, en particulier +celle sur la "Configuration de votre mot de passe sur GitLab". + +* Installer Git +** Linux (Debian, Ubuntu) +Nous ne fournissons ici que des instructions pour les distributions +basées sur Debian. N'hésitez pas à contribuer à ce document en +fournissant des informations à jour sur les autres distributions +(RedHat, Fedora, par exemple). + +Run (as root) : +#+begin_src sh :results output :exports both +apt-get update ; apt-get install git +#+end_src +** Mac OSX et Windows +- Télécharger et installer Git depuis le [[https://git-scm.com/downloads][site Git]]. +- Clients Git optionnels (ne devraient pas être nécessaires si vous + travaillez dans RStudio) : + - [[https://www.sourcetreeapp.com/][SourceTree]] + - [[https://desktop.github.com/][GitHub Desktop]] + #+BEGIN_QUOTE + Semble fonctionner avec GitLab et https (voir [[https://github.com/desktop/desktop/issues/852][discussion]]). + #+END_QUOTE +* Configurer Git +** Dire à Git qui vous êtes : nom et email +1. Ouvrir un terminal. +2. Définir un nom d'utilisateur et un email dans Git : + #+begin_src shell :results output :exports both + git config --global user.name "Mona Lisa" + git config --global user.email "email@example.com" + #+end_src + + #+RESULTS: + +3. Confirmer que vous avez correctement défini le nom d'utilisateur et + l'email Git : + #+begin_src shell :results output :exports both + git config --global user.name + git config --global user.email + #+end_src + + #+RESULTS: + : Mona Lisa + : email@example.com +** Gérer les proxy +Vous êtes peut-être derrière un proxy, auquel cas vous pouvez avoir +des problèmes de clonage ou d’extraction à partir d’un dépôt distant, +ou une erreur telle que : +=unable to access... Couldn't resolve host...= + +Dans ce cas, envisagez quelque chose comme ceci : +#+begin_src shell :results output :exports both +git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port +#+end_src + +Le =proxyPassword= sera stocké en texte brut (non crypté) dans votre +fichier ~.gitconfig~, ce que vous ne souhaitez peut-être pas. Dans ce +cas, supprimez-le de l'URL et vous serez invité à le saisir chaque fois +que vous en aurez besoin. +** Récupérer votre mot de passe par défaut sur GitLab (et le changer éventuellement) +*Avertissement (utilisateurs Jupyter) :* changer votre mot de passe +Gitlab par défaut vous empêchera de commiter les notebooks Jupyter que +nous avons déployés pour le MOOC. Vous devrez effectuer l’étape +supplémentaire de modification de votre =~/.git-credentials= dans +l’environnement Jupyter (éventuellement plusieurs fois). + +1. Récupérer votre mot de passe par défaut en utilisant l'outil [[https://app-learninglab.inria.fr/jupyterhub/services/password][Gitlab + credentials retrieval]] comme décrit dans la [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/7508aece244548349424dfd61ee3ba85][ressource correspondante]]. + #+BEGIN_CENTER + [[file:gitlab_images/password_retrieval.png]] + #+END_CENTER + La première séquence de caractères longue et laide est votre + identifiant GitLab qu'il est facile de trouver une fois que vous + êtes connecté à Gitlab. Cependant la seconde séquence de caractères + est votre mot de passe et cette page Web est le seul endroit où + vous pouvez le trouver. Nous avons utilisé le mécanisme + d'authentification FUN pour propager vos informations + d'identification de sorte que seulement vous puissiez y + accéder. Vous devrez utiliser ce mot de passe lorsque vous + essaierez de propager des modifications de votre ordinateur vers + GitLab. + + /Note : Vous devez accéder à cette page Web à partir de la/ + /plate-forme FUN, sinon vous risquez d'obtenir une erreur 405 en/ + /essayant d'accéder directement à + [[https://app-learninglab.inria.fr/jupyterhub/services/password]]./ + #+BEGIN_CENTER + [[file:gitlab_images/erreur405.png]] + #+END_CENTER +2. Accéder à [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/xblock/block-v1:inria+41016+session01bis+type@lti+block@05a0ce425f1741e5bee5049040f70529/handler/preview_handler][GitLab]]. + + /Note : Vous devez à nouveau accéder à Gitlab à partir de la plate-forme/ + /FUN, sinon vous risquez d'obtenir une erreur 405 en essayant + d'accéder directement à/ + https://app-learninglab.inria.fr/gitlab/users/sign_in/. +3. Cliquez sur le premier bouton =Sign in=. Vous pouvez également + utiliser l'identifiant/mot de passe que vous venez de récupérer et + utiliser le second bouton =Sign in=. Le second bouton permet de plus + de se connecter sans passer par la plateforme FUN une fois que vous + connaissez votre identifiant/mot de passe. + #+BEGIN_CENTER + [[file:gitlab_images/signin.png]] + #+END_CENTER +4. Si vous souhaitez modifier votre mot de passe, accédez à =Account > + Settings > Password= et définissez votre mot de passe à l'aide du mot + de passe par défaut que vous venez de récupérer. Encore une fois, si + vous utilisez les notebooks Jupyter que nous avons déployés pour le + MOOC, n’oubliez pas que changer votre mot de passe Gitlab par défaut + vous empêchera de les commiter. Vous devrez effectuer l’étape + supplémentaire consistant à changer votre =~/.git-credentials= + Jupyter via une console Jupyter (voir section suivante). + + #+BEGIN_CENTER + [[file:gitlab_images/password.png]] + #+END_CENTER +** Enregistrer votre mot de passe localement +Si vous clonez votre dépôt en collant simplement l'URL de +GitLab, vous serez invité à saisir votre identifiant et votre mot de +passe chaque fois que vous souhaitez propager vos modifications +locales, ce qui est fastidieux. C’est pourquoi vous pouvez demander à +Git de se rappeler de votre identifiant et votre mot de passe comme +suit : + +#+begin_src shell :results output :exports both +git config --global credential.helper cache # remember my password +git config --global credential.helper "cache --timeout=3600" # for one hour at most +#+end_src +Avec cette configuration, vous serez invité à saisir votre mot de +passe, mais celui-ci sera mis en cache et ne sera plus demandé pendant +une heure. Vous voudrez peut-être lire [[https://stackoverflow.com/questions/5343068/is-there-a-way-to-skip-password-typing-when-using-https-on-github][ces instructions]] pour mieux +comprendre comment tout cela fonctionne. + +Si vous souhaitez que votre mot de passe soit mémorisé en permanence, +vous devez utiliser cette commande : +#+begin_src shell :results output :exports both +git config credential.helper store +#+end_src +Votre mot de passe sera alors stocké dans un fichier =.git-credentials= +en texte brut (non-crypté). Sur une machine parfaitement sécurisée, +cela peut être très bien... ou pas... ;) Utilisez cette possibilité à +vos risques et périls. +** Optionnel : authentification par SSH +Il existe deux manières d'authentifier et de synchroniser votre +dépôt local avec GitLab : via HTTPS ou via SSH. Le premier est ce +qui vient d'être décrit et ne nécessite aucune installation de +logiciel particulier sur votre machine, c'est donc ce que je +recommande pour ce MOOC. Pourtant, je préfère le second (bien que +cela puisse paraître un peu plus technique), c'est pourquoi je le +décris ici. Cela consiste à installer SSH, à créer une paire de clés +ou des clés privée/publique et à télécharger votre clé publique SSH +sur GitLab. Cette section fournit des informations sur la procédure à +suivre. + +*** Installer SSH +**** Linux (Debian, Ubuntu) +Nous ne fournissons ici que des instructions pour les distributions +basées sur Debian. N'hésitez pas à contribuer à ce document en +fournissant des informations à jour sur les autres distributions +(RedHat, Fedora, par exemple). + +Run (as root) : +#+begin_src sh :results output :exports both +apt-get update ; apt-get install openssh-client +#+end_src +**** macOS +C'est installé par défaut donc vous n'avez rien à faire. +**** Windows +Vous devez installer le client [[https://www.ssh.com/ssh/putty/windows/][Putty]]. Une fois l’installation +terminée, suivez la section [[https://www.ssh.com/ssh/putty/windows/puttygen][PuTTYgen - Key Generator for PuTTY on +Windows]]. +*** Configurer SSH sur GitLab +Vous trouverez [[https://docs.gitlab.com/ee/ssh/][ici]] les explications officielles sur la configuration +de votre clé SSH sur GitLab. Vous pouvez aussi regarder cette vidéo : +#+BEGIN_EXPORT html + +#+END_EXPORT +* Utiliser Git par lignes de commandes pour synchroniser vos fichiers locaux avec Gitlab +Cette section décrit un moyen générique (par lignes de commandes) de +synchroniser vos fichiers locaux avec Gitlab. Vous n'en aurez pas +besoin si vous suivez le parcours Jupyter. Si vous suivez le parcours +RStudio, toutes ces opérations peuvent être effectuées via RStudio et +vous voudrez peut-être lire [[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/1a4f58a1efed437c93a9f5c5f15df428][les instructions correspondantes]]. Si vous +suivez le chemin Org-Mode, toutes ces opérations peuvent être +effectuées via Magit et vous voudrez peut-être lire +[[https://www.fun-mooc.fr/courses/course-v1:inria+41016+session01bis/jump_to_id/508299f7373449a3939faa5b11462bc4][les instructions correspondantes]]. + + +Voici d'autres moyens d'apprendre Git par lignes de commandes : +- Le [[http://swcarpentry.github.io/git-novice/][Software Carpentry git tutorial]] +- Le livre Pro Git (gratuit) en [[https://git-scm.com/book/en/v2][englais]] ou en [[https://git-scm.com/book/fr/v2][français]]. Les deux + premiers chapitres suffisent pour bien commencer. +- Le site [[https://learngitbranching.js.org/][Apprenez Git Branching]] permet d'apprendre Git + interactivement et de comprendre les branches. + +Maintenant, commençons ! +1. Récupérer l'URL du dépôt + #+BEGIN_CENTER + [[file:rstudio_images/adresse_depot.png]] + #+END_CENTER +2. Cloner le dépôt + #+begin_src shell :results output :exports both + cd /the/directory/where/you/want/to/clone/your/repository + git clone https://app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git + #+end_src + Alternativement, vous pouvez vouloir indiquer votre identifiant + maintenant, bien que je vous suggère plutôt de suivre les + instructions de la partie /Enregistrer votre mot de passe localement/. + #+begin_src shell :results output :exports both + git clone https://xxx@app-learninglab.inria.fr/gitlab/xxx/mooc-rr.git + #+end_src + Maintenant un répertoire =mooc-rr= a été créé sur votre ordinateur. +3. Inspecter le répertoire correspondant au dépôt + #+begin_src shell :results output :exports both + cd mooc-rr + ls # (Unix) + dir # (Windows) + #+end_src +4. Synchroniser avec GitLab + + Vous devez indiquer les fichiers à suivre (=git add=) et les valider + localement (=git commit=) avant de pouvoir les transférer (=git push=) + à GitLab. Le =git status= vous indiquera si les fichiers sont + suivis/modifiés/commités/... + + Supposons que vous venez de créer un fichier =fichier.txt= à la + racine du répertoire =mooc-rr=. + + #+begin_src shell :results output :exports both + git status + #+end_src + + #+BEGIN_CENTER + [[file:gitlab_images/status1.png]] + #+END_CENTER + + #+begin_src shell :results output :exports both + git add fichier.txt + git status + #+end_src + + #+BEGIN_CENTER + [[file:gitlab_images/status2.png]] + #+END_CENTER + + #+begin_src shell :results output :exports both + git commit -m "message commit" + #+end_src + + #+BEGIN_CENTER + [[file:gitlab_images/commit_git.png]] + #+END_CENTER + + #+begin_src shell :results output :exports both + git status + #+end_src + + #+BEGIN_CENTER + [[file:gitlab_images/status3.png]] + #+END_CENTER + + Le fichier peut ensuite être transféré vers GitLab : + #+begin_src shell :results output :exports both + git push + #+end_src + + À ce stade, Git vous demandera votre identifiant/mot de passe, + sauf si vous avez suivi les instructions de la partie /Enregistrer + votre mot de passe localement/. + + NB : vous ne serez pas autorisé à propager vos modifications dans + GitLab si d'autres modifications ont été propagées entre temps (par + exemple par quelqu'un d'autre). + + #+BEGIN_CENTER + [[file:gitlab_images/rejected.png]] + #+END_CENTER + +5. Synchronisation à partir de Gitlab : pour éviter le problème + précédent, vous devez d’abord récupérer les modifications distantes + de GitLab et les appliquer localement. + + #+begin_src shell :results output :exports both + git pull + #+end_src + Alors seulement pourrez-vous exécuter le =git push=. + +