La Forge des Communs Numériques Éducatifs — Tutoriel 2/3 : Gérer ses fichiers avec git

• Avertissement
• Utilisation de git
• Quels fichiers (ne pas) inclure ?
• Un peu de droit d'auteur

Dans cette partie du tutoriels, vous allez apprendre à :

• créer un dépôt sur la forge (un répertoire sur la forge synchronisé avec un répertoire sur votre ordinateur) ;
• ajouter des fichiers à ce dépôt ;
• synchroniser les deux dépôts (sur la forge et sur votre ordinateur) ;
• utiliser ce dépôt pour synchroniser plusieurs supports (par exemple votre clef USB et votre ordinateur) ;
• travailler à plusieurs sur ce dépôt.

Ainsi que quelques bonnes pratiques en lien avec ce dépôt.

La publication de contenu sur le web à partir de ce dépôt sera vue dans la troisième partie.

Avertissement

— Voici git. Ça permet de gérer le travail collaboratif grâce un a modèle distribué de théorie des graphes.

— Super. Ça fonctionne comment ?

— Aucune idée. Apprends par cœur ces quelques commandes et exécute-les pour synchroniser. Si tu obtiens des erreurs, sauvegarde ton travail quelque part, supprime le projet, et télécharge une nouvelle copie.

Source, publié sous licence Creative Commons by-nc 2.5

Je vous présente ici l'utilisation de git, un logiciel technique qui permet de faire des choses complexes. Les quelques commandes que je présente ici sont assez simple et devraient vous permettre de pouvoir utiliser la forge, mais il est très facile de se retrouver avec git dans une situation apparement sans solution, autre que tout effacer et télécharger une copie fraîche. Cela m'est arrivé plusieurs fois à mes débuts, mais je n'ai malgré tout jamais perdu de données.

Ce logiciel est néanmoins un excellent outil, utilisé par énormément d'informaticiens, amateurs ou professionnels (voir la liste en bas de cette page).

Bon courage !

Utilisation de git

Installation de git

Commencez par installer le logiciel git.

Initialisation du projet

La première étape est l'initialisation du projet sur la forge, qui peut se faire de plusieurs manières.

Option 1 : À partir d'un dépôt existant

1. Pour copier un dépôt existant, rendez vous sur la page correspondante, puis cliquez sur « Créer une bifurcation »

   

   Remplissez les quelques informations demandées (la plupart optionnelles, sauf l'espace de nommage, pour lequel vous pouvez sélectionner votre identifiant).

2. Dans le menu « Code », copiez ensuite l'adresse commençant par git@forge.apps.education.fr:.

   

3. Enfin, dans un terminal, placez-vous dans le dossier dans lequel vous voulez cloner le dépôt, puis lancez la commande suivante (où git@forge.apps.education.fr:… est à remplacer par l'adresse copiée à l'étape précédente) :

   $ git clone git@forge.apps.education.fr:…
   

4. Vous avez maintenant une copie du dépôt, dans un dossier dont le nom est l'identifiant du projet.

Option 2 : En créant un nouveau projet

1. Sur la page d'accueuil de votre projet, dans le menu « + », cliquez sur « Nouveau projet/dépôt ».

   

2. Vous pouvez choisir entre créer un projet vide, et créer à partir d'un modèle (utile pour créer un site web).

3. Choisissez le nom du projet (pour les humains) et son identifiant (pour les ordinateurs), et sa visibilité (privé, interne, ou public).

   

4. Vous pouvez maintenant cloner votre projet sur votre ordinateur, en commençant par, dans le menu « Code », copier l'adresse commençant par git@forge.apps.education.fr:.

   

5. Enfin, dans un terminal, placez-vous dans le dossier dans lequel vous voulez cloner le dépôt, puis lancez la commande suivante (où git@forge.apps.education.fr:… est à remplacer par l'adresse copiée à l'étape précédente) :

   $ git clone git@forge.apps.education.fr:…
   

6. Vous avez maintenant une copie du dépôt, dans un dossier dont le nom est l'identifiant du projet.

Ajouter des fichiers

Vous avez créé votre dépôt, et vous pouvez maintenant y travailler. Pour cet exemple, nous avons créé deux fichiers : un fichier .tex, et un fichier .odt. Remarquons que si git est capable de manipuler tous types de fichiers, il est plutôt conçu pour manipuler des fichiers texte (txt, markdown, LaTeX, html…), et la manipulation de tels fichiers sera plus simple qu'avec des fichiers binaires (LibreOffice, Microsoft Office, images…).

Voici les quatre commandes nécessaires pour envoyer les fichiers sur la forge, à exécuter dans le dossier du dépôt.

git status : Afficher le statut des fichiers

Dans l'exemple suivant, nous voyons que les quatre fichiers intro.… ainsi que progression.odt ne sont pas encore connus de git.

$ git status
Sur la branche main
Votre branche est à jour avec 'origin/main'.

Fichiers non suivis:
  (utilisez "git add <fichier>..." pour inclure dans ce qui sera validé)
        intro.aux
        intro.log
        intro.pdf
        intro.tex
        progression.odt

aucune modification ajoutée à la validation mais des fichiers non suivis sont présents (utilisez "git add" pour les suivre)

git add : Ajouter des fichiers (ou des modifications) au dépôt

Nous allons maintenant ajouter les deux fichiers intro.tex et progression.odt au dépôt (les autres fichiers intro.aux, intro.log, intro.pdf n'ont pas besoin d'être ajoutés : seule la source va l'être).

$ git add intro.tex progression.odt

Cette commande n'affiche rien : c'est normal, cela veut dire que tout s'est bien passé. Vérifions maintenant l'état du dépôt avec git status.

$ git status
Sur la branche main
Votre branche est à jour avec 'origin/main'.

Modifications qui seront validées :
  (utilisez "git restore --staged <fichier>..." pour désindexer)
        nouveau fichier : intro.tex
        nouveau fichier : progression.odt

Fichiers non suivis:
  (utilisez "git add <fichier>..." pour inclure dans ce qui sera validé)
        intro.aux
        intro.log
        intro.pdf

Les deux nouveaux fichiers ont bien été ajoutés, les trois autres sont toujours inconnés.

Parenthèse : Le fichier .gitignore

Les fichiers .aux, .log, .pdf ne seront jamais ajoutés au dépôt. Nous pouvons dire à git de les ignorer en écrivant les lignes suivantes dans un fichier nommé .gitignore :

*.aux
*.log
*.pdf

Ce fichier .gitignore peut lui-même être ajouté au dépôt. Désormais, même si ces fichiers sont présents, git status ne les affiche plus.

$ git add .gitignore
$ git status
Sur la branche main
Votre branche est à jour avec 'origin/main'.

Modifications qui seront validées :
  (utilisez "git restore --staged <fichier>..." pour désindexer)
        nouveau fichier : .gitignore
        nouveau fichier : intro.tex
        nouveau fichier : progression.odt

git commit : Valider les modifications

Une fois ces fichiers ajouté, nous devons valider ces modifications, avec git commit. Cette commande va nous demander un commentaire pour cette validation (utile pour documenter l'histoire des modifications, même si je m'en sers assez peu pour mes cours).

$ git commit
[main dc4550b] premier commit
 3 files changed, 130 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 intro.tex
 create mode 100644 progression.odt

Nous voyons maintenant avec git status qu'un commit est prêt à être envoyé sur la forge.

$ git status
Sur la branche main
Votre branche est en avance sur 'origin/main' de 1 commit.
  (utilisez "git push" pour publier vos commits locaux)

rien à valider, la copie de travail est propre

git push : Téléverser les modifications

Enfin, les modifications validées avec git commit peuvent être envoyées sur la forge avec git push.

$ git push
Énumération des objets: 6, fait.
Décompte des objets: 100% (6/6), fait.
Compression par delta en utilisant jusqu'à 4 fils d'exécution
Compression des objets: 100% (4/4), fait.
Écriture des objets: 100% (5/5), 48.07 Kio | 16.02 Mio/s, fait.
Total 5 (delta 0), réutilisés 0 (delta 0), réutilisés du pack 0
To forge.apps.education.fr:germainsophie/cours-seconde-generale.git
   7d98cf5..dc4550b  main -> main

En allant sur la forge, nous voyons maintenant que les trois nouveaux fichiers ont bien été envoyés.

Modifier des fichiers

Vous travaillez vos cours, et vous avez modifié vos fichiers. Il faut maintenant valider les modifications.

git diff : Afficher les modifications

Commençons par regarder le statut des fichiers avec git status.

$ git status
Sur la branche main
Votre branche est à jour avec 'origin/main'.

Modifications qui ne seront pas validées :
  (utilisez "git add <fichier>..." pour mettre à jour ce qui sera validé)
  (utilisez "git restore <fichier>..." pour annuler les modifications dans le répertoire de travail)
        modifié :         intro.tex
        modifié :         progression.odt
aucune modification n'a été ajoutée à la validation (utilisez "git add" ou "git commit -a")

Nous voyons que les deux fichiers ont été modifiés. Avant de valider ces modifications, nous pouvons voir les différences avec git diff.

$ git diff
diff --git a/intro.tex b/intro.tex
index 41ab5ce..5434513 100644
--- a/intro.tex
+++ b/intro.tex
@@ -8,10 +8,10 @@
 % Compiler avec lualatex:
 %$ lualatex $basename

-\documentclass[11pt]{article}
+\documentclass[12pt]{article}

 \usepackage[
-  a5paper,
+  a4paper,
   includehead,
   margin=8mm,
   headsep=4mm,
diff --git a/progression.odt b/progression.odt
index ab6d1ae..ea7e024 100644

Nous pouvons observer que :

• les modifications lignes par ligne de intro.tex sont affichées, parce que c'est un fichier texte ;
• git nous dit que le fichier progression.odt a été modifié, sans nous préciser les modifications, parce que c'est un fichier binaire.

Il est possible de configurer git pour afficher les différences des fichiers binaires, mais c'est au delà de ce tutoriel (et c'est parfois un peu du bricolage).

Nous pouvons maintenant ajouter ces modifications, les valider, et envoyer tout cela sur la forge.

$ git add intro.tex progression.odt
$ git commit
[main 94431d1] modif
 2 files changed, 2 insertions(+), 2 deletions(-)
$ git push
Énumération des objets: 7, fait.
Décompte des objets: 100% (7/7), fait.
Compression par delta en utilisant jusqu'à 4 fils d'exécution
Compression des objets: 100% (4/4), fait.
Écriture des objets: 100% (4/4), 370 octets | 370.00 Kio/s, fait.
Total 4 (delta 3), réutilisés 0 (delta 0), réutilisés du pack 0
To forge.apps.education.fr:germainsophie/cours-seconde-generale.git
   dc4550b..94431d1  main -> main

Synchroniser deux supports

Maintenant que vous arrivez à envoyer vos fichiers depuis votre ordinateur vers la forge, vous aimeriez synchroniser un répertoire de votre clef USB avec ce même dépôt, pour pouvoir travailler indifféremment sur votre ordinateur ou sur cette clef.

Cloner le dépôt

Déplacez-vous sur la clef USB, puis clonez le dépôt avec la même commande git clone que précédemment.

$ git clone git@forge.apps.education.fr:…

git push et git pull : Téléverser et télécharger les modifications

Comme vu précédemment, quand vous faites une modification sur un fichier, vous pouvez la valider et l'envoyer sur la forge avec git push.

Pour récupérer cette modification sur cet autre support, utilisez git pull.

$ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
Dépaquetage des objets: 100% (3/3), 298 octets | 298.00 Kio/s, fait.
Depuis forge.apps.education.fr:germainsophie/cours-seconde-generale
   94431d1..3f59aec  main       -> origin/main
Mise à jour 94431d1..3f59aec
Fast-forward
 intro.tex | 4 ----
 1 file changed, 4 deletions(-)

Régler les conflits

Que se passe-t-il si vous avez modifié un fichier sur chacun des deux supports, sans les synchroniser avant ? Lors du git pull, git vous signale le conflit.

$ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
Dépaquetage des objets: 100% (3/3), 288 octets | 288.00 Kio/s, fait.
Depuis forge.apps.education.fr:paternaultlouis/cours-seconde-generale
   3f59aec..fedda5e  main       -> origin/main
astuce: Des branches divergentes ne peuvent pas être gérées en avance rapide, vous devez soit :
astuce: 
astuce:         git merge --no-ff
astuce: 
astuce: ou :
astuce: 
astuce:         git rebase
astuce: 
astuce: Disable this message with "git config advice.diverging false"
fatal : Pas possible d'avancer rapidement, abandon.

Git nous signale ici qu'il y a un souci. Dans les cas simples, un git merge permet de fusionner les deux modifications, en demandant à l'utilisateur·ice un message de validation.

Dans les cas plus compliqués, git mergetool permet de vous accompagner dans la résolution des conflits.

Voir l'historique

Enfin, deux outils permettent de voir l'historique d'un dépôt.

1. En ligne de commande, vous pouvez utiliser git log.

   $ git log
   commit cb5821e7d0c4bd31c2c07767136ddb659fd5b335 (HEAD -> main, origin/main, framagit/main)
   Author: Sophie Germain <sophie.germain@example.fr>
   Date:   Thu Apr 25 12:45:01 2024 +0200
   
       DS sur les vecteurs
   
   commit 63a4e3c09a092f8c1062e7823105cb0a27e32a3b
   Author: Sophie Germain <sophie.germain@example.fr>
   Date:   Thu Apr 25 07:55:47 2024 +0200
   
       typo
   

2. Avec une interface graphique, avec par expmel gitg.

   

Quels fichiers (ne pas) inclure ?

Dépôt privé ou public

Tout ce que vous publiez sera associé à votre nom, y compris vos bêtises, vos erreurs, vos errements de jeunesse, etc.

Vous perdez le contrôle de tout ce que vous publiez, et votre travail pourra être copié ailleurs sans votre accord, modifié, dégradé, d'autres pourront s'en attribuer la paternité, etc.

Si cela ne vous convient pas, assurez-vous que votre dépôt est bien privé.

Et si vous publiez des données vraiment sensibles, ne les publiez pas, même en privée : des accidents ou des fuites de données peuvent arriver, même sur les serveurs de l'État.

Fichiers « inutiles » ?

Les bonnes pratiques conseillent de ne pas ajouter à votre dépôt les fichiers inutiles (traces de compilations en LaTeX par exemple), ou les fichiers qui peuvent être reconstruits à partir d'autres fichiers de l'archive (pas de fichiers PDF si le fichier source est aussi dans l'archive). En effet, c'est inutile, et cela va nous embêter par la suite, car nous allons devoir valider des modifications sur ces fichiers qui ne sont pas importantes, et qui ne sont pas forcément synchronisée avec les modifications correspondantes faites sur le fichier source.

Une autre raison est le gain de place. Par exemple, dans le dépôt de mon cours de mathématiques de secondes, les sources seules occupent 8,3 Mo, alors que les fichiers compilés occupent 65 Mo, soit près de huit fois plus de place.

Comment, alors, diffuser aussi les fichiers compilés (notamment les PDF) ? Cette question sera abordée dans la prochaine partie du tutoriel.

Données personnelles

Ne mettez dans vos dépôts, même privés, aucune donnée personnelle de vos élèves (ou sur d'autres personnes), même une simple liste de noms, ou une copie d'élève même anonymisée. Ce n'est pas parce que la forge est gérée par notre ministère qu'elle est automatiquement « RGPD compatible ». D'ailleurs, aucun service n'est « RGPD compatible » : le RGPD n'est pas une étiquette appliquée à une application ou un site web, c'est un processus appliqué à un traitement de données :

• traitement de donnée : seul un traitement bien particulier est autorisé par le RGPD. Par exemple, il est interdit de trier ses élèves selon leur couleur de peau ou leur religion sur Pronote, bien que l'application soit autorisée. En effet, ce traitement des données des élèves n'a pas été autorisé ;
• processus : la forge n'est pas automatiquement compatible RGPD. Pour que soit le cas, il faut que le traitement des données ait recueilli l'accord des élèves ou des parents, et soit validé par le conseil d'administration de votre établissement (parmi d'autres choses). Référez-vous à la page 15 (« Le RGPD en quatre étapes ») de la brochure du réseau Canopé « Les Données à caractère personnel », dont je recommande la lecture.

Un peu de droit d'auteur

Les œuvres des autres

Si votre projet est public, vos fichiers sont accessibles à tous et toutes sur la toile. Il faut donc vous assurer que pour chacun des fichiers de votre dépôt :

• vous en êtes l'auteur·ice ;
• ou vous avez le droit de copier ce fichier (dans le domaine public par exemple) ;
• ou vous avez l'autorisation de l'auteur de copier de fichier (par exemple, s'il a été publié sous licence Creative Commons).

Dans tous les cas, si vous n'êtes pas l'auteur·ice du fichier, vous devez absolument attribuer correctement le fichier, c'est-à-dire donner le nom de l'auteur·ice original·e.

Cet article répond à quelques notions sur le droit d'auteur dans nos classes.

Vos œuvres

Chacun de vos fichiers, vos devoirs, vos exercices distribués à vos élèves, est protégé par le droit d'auteur au même titre que le Boléro, le dernier Star Wars, le tube à la mode, ou les Misérables. Sans précision de votre part, le public (vos collègues par exemple) ont le droit de voir ces fichiers, mais c'est tout : vous interdisez implicitement au monde entier de les télécharger, les modifier, les réutiliser en classe, etc. En effet, en droit d'auteur, mise à part quelques exceptions¹, tout est interdit, sauf ce qui est explicitement autorisé.

Pour autoriser la réutilisation de vos œuvres, il faut que vous en donniez l'autorisation. Il est conseillé de le faire avec une des licences Creative Commons, qui ont été conçues par des avocats, et couvre tous les cas bizarres auxquels nous n'avions même pas pensé. Sauf exception, tous mes cours sont sous licence Creative Commons by-sa, mais vous avez le choix. Toutes les licences autorisent la réutilisation, à condition de mentionner l'auteur, et en plus :

• Creative Commons by : Vous autorisez la réutilisation, les modifications, y compris dans un cadre commercial, à condition que votre nom soit cité.
• Creative Commons by nc : Vous autorisez la réutilisation et les modifications, seulement dans un cadre non commercial.
• Creative Commons by nc nd : Vous autorisez la réutilisation, mais pas les modifications, et uniquement dans un cadre non commercial.
• Creative Commons by nc sa : Vous autorisez la réutilisation et les modifications, de manière non commerciale, à condition que l'œuvre modifiée soit elle-même distribuée avec la même licence.
• Creative Commons by nd : Vous autorisez la réutilisation, y compris dans un cadre commercial, mais pas les modifications.
• Creative Commons by sa : Vous autorisez la réutilisation et les modifications, y compris dans un cadre commercial, à condition que l'œuvre modifiée utilise la même licence.

J'en profite pour expliquer mon choix de licence, Creative Commons by-sa :

• attribution : j'impose que mon nom soit cité (c'est une obligation dans le droit français) ;
• réutilisation : j'autorise que mon travail soit réutilisé. Si j'ai fait du bon travail, et que cela facilite la vie de mes collègues, tant mieux !
• modification : j'autorise les modifications de mon travail (à condition que mon nom reste) : cela permet aux collègues qui réutilisent mon travail de l'adapter à leur cas, de l'améliorer, de corriger les erreurs, de le traduire, etc. ;
• partage dans les mêmes conditions : tout cela est autorisé à condition que le résultat soit partagé avec la même licence : si quelqu'un prend mon travail, et le modifie, je veux qu'il le distribue avec la même licence, pour autoriser aux autres ce qu'il s'est permis avec mon travail ;
• autorisation des utilisations commerciales : j'autorise l'utilisation de mon travail dans un cadre commercial (un manuel qui serait vendu, par exemple), sans que je touche un centime, à condition que ce soit fait avec la même licence. Ainsi, mon travail intégré (et modifié) pour le manuel, même vendu, pourra être librement copié et diffusé².