Git et GitHub

Versionner, collaborer et garder des traces de travail utiles

Aurélien Nicosia

Pourquoi cette capsule au premier cours?

Les outils du cours

Git et GitHub ne servent pas seulement à remettre des fichiers. Ils permettent de conserver l’histoire d’un projet, de vérifier ce qui a été fait et de travailler avec d’autres personnes sans perdre le fil.

Comprendre la différence entre Git et GitHub.
Lire l’état d’un dépôt avant d’agir.
Créer des commits qui expliquent le travail.
Savoir quoi protéger avant de publier.

Le problème que nous voulons éviter

« Quel fichier est le bon? Qu’est-ce qui a changé? Est-ce que je peux revenir en arrière? »

Un projet de science des données produit rapidement beaucoup de traces:

  • données importées ou nettoyées;
  • scripts R et fonctions;
  • figures, tableaux et rapports Quarto;
  • décisions, corrections et commentaires;
  • contributions de plusieurs personnes.

Sans historique explicite, on garde souvent des copies comme analyse_finale_v7_vraiment_finale.R. Elles n’expliquent ni le changement, ni sa raison, ni la version qui a produit un résultat.

Le contrôle de version, en une phrase

Le contrôle de version enregistre les changements d’un ensemble de fichiers au fil du temps afin de pouvoir comparer, comprendre et retrouver des versions antérieures.

Ce que cela rend possible

  • retrouver un état stable;
  • comparer deux versions;
  • identifier l’origine d’une modification;
  • conserver une trace des choix.

Ce que cela ne garantit pas

  • que le code est correct;
  • que les données sont autorisées à être publiées;
  • qu’un projet est reproductible sans vérification;
  • qu’une personne comprend son propre commit.

La responsabilité scientifique reste humaine: Git conserve une trace, mais ne valide pas automatiquement le raisonnement.

Git et GitHub ne sont pas la même chose

Outil Où? Rôle principal
Git Sur votre ordinateur, dans le dépôt local Versionner les fichiers et leur historique
GitHub Service en ligne Héberger, partager, discuter, relire et organiser des projets Git

Git fonctionne localement. Un commit est donc possible même si le réseau ou l’authentification GitHub ne fonctionne pas encore.

GitHub ajoute un dépôt distant, une interface Web et des outils de collaboration. C’est là que l’on peut voir les commits, ouvrir une issue, proposer une pull request ou publier un site lorsque le projet le prévoit.

Une carte simple du projet

Votre ordinateur

Un dossier de projet, les fichiers et l’historique Git local.

Vous pouvez modifier, comparer et committer ici.

git push → ← git pull

GitHub

Une copie distante du dépôt et un espace de collaboration.

Vous pouvez partager, relire et discuter ici.

Le mot origin désigne souvent le dépôt GitHub configuré comme dépôt distant. C’est une convention de nom, pas un service distinct.

Les mots qui reviennent tout le temps

Dépôt ou repository

Le dossier du projet et son historique Git.

Commit

Un point d’historique qui enregistre un ensemble ciblé de changements.

Diff

La différence entre deux états de fichiers.

Branche

Une ligne de travail distincte. Elle isole une modification avant son intégration.

Remote

Un dépôt distant connu du dépôt local, souvent GitHub.

README

La porte d’entrée du projet: objectif, structure et procédure minimale.

L’historique est une suite de décisions

1. DépartImporter les données brutes.
2. NettoyageCorriger les types et valeurs manquantes.
3. AnalyseAjouter une fonction ou un modèle.
4. VérificationContrôler les résultats et le rapport.

Chaque étape peut devenir un ou plusieurs commits lorsque le travail atteint un état qui mérite d’être conservé.

Un commit n’est pas un bouton « fini ». C’est une trace précise: ce qui a changé et pourquoi cette étape est maintenant enregistrée.

Un commit utile répond à deux questions

Peu utile

update
test
ok
version finale

Ces messages obligent les autres personnes, ou vous-même dans trois semaines, à ouvrir le diff pour comprendre l’intention.

Lisible

Ajouter le diagnostic de l’environnement
Corriger le chemin relatif des données
Documenter la procédure de reproduction

Le message décrit l’intention et le diff montre le détail.

Un bon test: une personne qui lit seulement la liste des commits peut-elle reconstituer le déroulement du projet?

Toujours commencer par observer

git status montre les fichiers que Git reconnaît, ceux qui ont changé et ceux qui sont prêts pour le prochain commit.

git status
git diff
  • git status répond: « Dans quel état est mon dépôt? »
  • git diff répond: « Qu’est-ce qui a changé dans les fichiers non indexés? »

Avant d’ajouter un fichier, lire son nom. Avant de committer, lire le contenu qui sera enregistré. Une interface graphique dans Positron ou RStudio peut aider, mais les questions restent les mêmes.

Une même action, trois façons de la faire

Intention Terminal RStudio Positron
Voir l’état git status Onglet Git: fichiers affichés Vue Source Control: liste Changes
Lire les changements git diff Sélectionner un fichier puis Diff Cliquer le fichier dans Changes
Préparer un fichier git add fichier Cocher le fichier dans l’onglet Git ou la fenêtre Commit Cliquer le + du fichier pour le placer dans Staged Changes
Enregistrer git commit -m “message” Commit, message, puis Commit dans la fenêtre Écrire le message, puis cliquer Commit
Envoyer git push Bouton Push … puis Push, ou Sync Changes
Récupérer git pull –ff-only Bouton Pull … puis Pull, ou Sync Changes

Les interfaces ne remplacent pas Git: elles exécutent les mêmes opérations. Sync Changes effectue un pull puis un push; il n’est pas une vérification neutre de l’état.

RStudio: où cliquer, dans l’ordre

Étape 1: voir et relire

Dans le projet RStudio, ouvrir l’onglet Git, généralement dans le panneau supérieur droit.

Sélectionner un fichier, puis cliquer Diff pour lire les changements avant de les enregistrer.

Étape 2: préparer et committer

Cocher uniquement les fichiers à inclure. Cliquer Commit.

Dans la fenêtre « Review Changes », vérifier les fichiers cochés, écrire le message, puis cliquer Commit.

Étape 3: partager

Une fois le commit créé localement, cliquer Push dans l’onglet Git ou le menu Git.

Utiliser Pull avant de commencer un bloc de travail collaboratif, seulement si l’état local est compris.

Si l’onglet Git n’apparaît pas, vérifier que le dossier a été ouvert comme projet RStudio et que Git est installé et reconnu par RStudio.

Positron: où cliquer, dans l’ordre

Étape 1: ouvrir Source Control

Cliquer l’icône Source Control dans la barre d’activité à gauche.

Si le dossier n’est pas encore un dépôt Git, cliquer Initialize Repository. S’il est déjà cloné, les fichiers apparaissent sous Changes.

Étape 2: relire et préparer

Cliquer un fichier dans Changes pour ouvrir le diff.

Cliquer le + près du fichier à inclure. Il se déplace vers Staged Changes. Ne pas tout préparer automatiquement sans avoir relu.

Étape 3: committer et synchroniser

Écrire un message dans la boîte de message de commit, puis cliquer Commit.

Pour une seule direction, ouvrir … et choisir Push ou Pull. Sync Changes combine les deux opérations.

Dans Positron, ne pas utiliser le bouton d’étincelles pour générer le message de commit dans ce premier exercice: le message doit expliquer votre propre décision.

Le cycle local minimal

Observergit status
Lire l’état.
ModifierÉditer, exécuter et vérifier.
Préparergit add
Choisir les fichiers.
Reliregit diff –staged
Voir le prochain commit.
Enregistrergit commit
Décrire l’intention.

Ce cycle crée un historique local. La synchronisation avec GitHub vient ensuite.

Le rôle de la zone d’index

Git ne commit pas automatiquement tous les changements. La zone d’index, souvent appelée staging area, permet de choisir ce qui entre dans le prochain commit.

# Voir ce qui existe et ce qui a changé
git status

# Préparer seulement le README
git add README.md

# Lire exactement ce qui sera committé
git diff --staged

# Enregistrer la décision
git commit -m "Documenter la structure du portfolio"

Cette étape intermédiaire aide à éviter les commits qui mélangent une correction, une figure temporaire et un fichier sensible.

Exemple: rendre une correction vérifiable

Supposons qu’un script lisait un fichier par un chemin propre à votre ordinateur.

# Fragile: le chemin dépend d'un ordinateur particulier
# donnees <- readr::read_csv("/Users/moi/projet/data/observations.csv")

# Portable: le chemin est relatif à la racine du projet
donnees <- readr::read_csv("data/observations.csv")

Un historique lisible peut distinguer:

  1. Ajouter la première importation des observations;
  2. Corriger le chemin de donnees pour le rendre portable;
  3. Verifier le rendu du rapport depuis la racine du projet.

La troisième étape est importante: un changement qui paraît plausible doit être exécuté et vérifié.

Quand GitHub entre en jeu

Après un ou plusieurs commits locaux, GitHub permet de mettre une copie du dépôt à distance et de travailler autour de cette copie.

# Vérifier le dépôt distant configuré
git remote -v

# Envoyer les commits locaux vers GitHub
git push

Avant un travail collaboratif, récupérer l’état partagé lorsque le dépôt est déjà configuré:

git pull --ff-only

Si cette dernière commande échoue, ne pas forcer une correction au hasard. Lire le message, conserver le travail local et demander de l’aide avec l’état observé.

GitHub ne remplace pas l’organisation du projet

GitHub rend visible

  • le README;
  • l’historique des commits;
  • les différences entre versions;
  • les discussions, issues et pull requests;
  • les résultats de validations automatisées, si le projet en possède.

Le dépôt doit déjà être compréhensible

  • fichiers nommés clairement;
  • structure cohérente;
  • chemins relatifs;
  • données et sorties documentées;
  • procédure de reproduction minimale.

Un dépôt désorganisé reste désorganisé après un git push.

Collaboration: la pull request

Une pull request propose de faire entrer des changements d’une branche dans une autre, souvent vers main. Elle sert à montrer le diff, discuter les choix et relire avant l’intégration.

Créer une brancheIsoler une tâche précise.
CommiterProduire des changements ciblés.
Ouvrir une PRExpliquer la proposition.
RelireCommenter, vérifier, ajuster.
FusionnerIntégrer après accord.

Au premier cours, l’objectif est de reconnaître ce cycle. Nous le pratiquerons progressivement; il n’est pas attendu que tout le monde maîtrise les branches aujourd’hui.

Ce qu’on lit dans une pull request

Partie Question utile
Titre et description Quel problème est traité? Quelle décision est proposée?
Commits Les étapes sont-elles ciblées et lisibles?
Fichiers modifiés Le changement est-il limité à ce qui est nécessaire?
Diff Chaque ligne ajoutée ou retirée est-elle justifiée?
Checks Quelles vérifications automatiques ont réussi ou échoué?
Discussion Les commentaires reçoivent-ils une réponse claire?

Une pull request n’est pas une formalité. C’est un objet de communication et de contrôle de qualité.

Travailler en équipe sans se marcher sur les pieds

Habitudes à installer

  • annoncer qui traite quelle tâche;
  • faire de petits commits cohérents;
  • pousser régulièrement lorsqu’il est prudent de partager;
  • lire une pull request avant de l’approuver;
  • documenter les décisions qui ne sont pas visibles dans le code.

Habitudes à éviter

  • modifier la même zone sans coordination;
  • committer des fichiers générés ou temporaires sans raison;
  • régler un conflit en supprimant du code sans le comprendre;
  • approuver une PR qui n’a pas été lue;
  • écrire un message du type fix sans contexte.

Les conflits sont un signal, pas une catastrophe

Un conflit apparaît lorsque Git ne peut pas décider seul comment combiner deux modifications incompatibles. Par exemple, deux personnes ont modifié la même ligne dans des directions différentes.

Réponse raisonnable

  1. arrêter et lire le message;
  2. identifier les fichiers concernés;
  3. comparer les intentions, pas seulement les lignes;
  4. choisir une version cohérente;
  5. exécuter les vérifications;
  6. documenter la résolution.

À ne pas faire

  • supprimer les marqueurs de conflit sans comprendre;
  • utiliser une commande proposée sur Internet sans savoir son effet;
  • forcer un push pour passer par-dessus le travail d’une autre personne;
  • jeter les changements locaux avant d’avoir compris leur rôle.

Protéger le projet et les personnes

Avant chaque commit, vérifier les noms et le contenu des fichiers ajoutés.

Ne jamais committer ou publier

  • mot de passe ou jeton d’accès;
  • clé SSH privée;
  • données confidentielles ou renseignements personnels;
  • fichier fourni sous une licence incompatible;
  • capture d’écran contenant des informations sensibles.

Réflexes utiles

  • utiliser .gitignore pour les fichiers locaux ou générés;
  • lire git status et git diff –staged;
  • demander avant de publier un fichier dont le statut est incertain;
  • protéger le compte GitHub avec un mot de passe unique et l’authentification à deux facteurs.

GitHub ne peut pas retirer la responsabilité de vérifier ce qui est partagé.

Votre compte GitHub: prêt pour le cours

Le compte est accessible et l’adresse courriel est vérifiée.
Le nom d’utilisateur est professionnel et durable.
Le profil ne contient pas de renseignement que vous ne souhaitez pas rendre public.
L’authentification à deux facteurs est activée.
Vous savez où voir les invitations aux dépôts ou aux organisations.
Vous ne partagez jamais un jeton ou une clé privée pour demander de l’aide.

Le cours peut demander une invitation à un dépôt ou à une organisation. Accepter seulement une invitation liée au cours et vérifier son origine avant de l’accepter.

Ce que Git et GitHub apportent au portfolio

Le portfolio du cours n’est pas une galerie de résultats parfaits. C’est une trace de travail que vous pourrez expliquer.

Preuve d’avancement

Les commits rendent visibles les étapes et les corrections.

Documentation

Le README et les journaux expliquent la structure et les choix.

Reproductibilité

Les scripts, chemins et rapports permettent de relancer le travail.

Une belle visualisation sans code, sans données documentées ni procédure de reproduction ne suffit pas à démontrer le travail réalisé.

Activité guidée du premier laboratoire

Aujourd’hui, l’objectif réaliste est de cloner le dépôt privé attribué, d’y créer une première trace personnelle et de comprendre son état.

1. ClonerRécupérer portfolio-stt4230-IDUL ou portfolio-stt6230-IDUL.
2. PersonnaliserCompléter le README et la trace de semaine 1.
3. VérifierExécuter le diagnostic R, Git et Quarto.
4. CommiterConserver une étape lisible localement.
5. SynchroniserPousser vers GitHub si l’accès est prêt.

Si le clonage bloque, ne pas créer un dépôt parallèle. Consigner la commande, le message complet, le compte GitHub utilisé et l’IDUL attendu. Si seul l’envoi bloque après le clonage, les commits locaux demeurent valables.

Démonstration: le minimum à savoir lire

# Après avoir cloné le dépôt attribué et ouvert sa racine
git status

# Après une modification volontaire de README.md
git add README.md
git diff --staged
git commit -m "Personnaliser le portfolio"

# Seulement lorsque le dépôt distant est configuré et que l'accès fonctionne
git push

À la fin de la démonstration, vous devez pouvoir répondre:

  • Où se trouve mon dépôt local?
  • Quel fichier vais-je réellement committer?
  • Qu’est-ce que mon message de commit explique?
  • Est-ce que je travaille bien dans le dépôt attribué, et la synchronisation GitHub est-elle réglée?

Si quelque chose bloque

Une bonne demande d’aide contient des faits vérifiables.

Contexte: ce que j’essayais de faire
Commande exécutée: la commande exacte
Résultat: le message complet, sans secret
État du dépôt: sortie de git status
Ce que j’ai déjà essayé: une ou deux actions précises

Éviter les diagnostics vagues comme « Git ne marche pas ». Une erreur précise est un point de départ utile pour la personne qui aide.

À retenir

Git est local

Il enregistre l’histoire du projet sur votre ordinateur. Les commits peuvent exister avant GitHub.

GitHub est collaboratif

Il héberge une copie distante et fournit des outils pour partager, relire et discuter.

La commande de départ est git status

Lire l’état avant d’ajouter, committer, pousser ou corriger.

Un commit est une explication

Séparer les intentions et écrire un message que vous comprendrez plus tard.

Ressources à garder

Les notions de contrôle de version et de cycle des fichiers suivent Pro Git. Les définitions et le déroulement des pull requests suivent la documentation GitHub consultée le 18 août 2026. La ressource Happy Git est particulièrement adaptée au travail avec R.