📋 Sommaire
🖥 1. C’est quoi GitHub Desktop ?
GitHub Desktop est une interface graphique Windows/Mac qui permet de gérer des repos Git sans taper de commandes dans un terminal. Vous voyez visuellement ce qui a changé, vous cliquez pour valider, vous poussez d’un bouton.
La différence entre Git et GitHub
Git
Le système de versionnage installé sur votre machine. Il enregistre chaque modification comme un instantané dans l’historique. C’est un outil local.
GitHub
La plateforme en ligne où les repos sont hébergés et partagés. GitHub.com est le serveur distant. Git est le moteur local qui synchronise avec ce serveur.
GitHub Desktop
L’interface graphique qui fait le pont entre votre machine (Git local) et GitHub.com. Elle traduit les commandes Git en clics.
Pourquoi utiliser GitHub Desktop ?
- Voir d’un coup d’œil tous les fichiers modifiés, les lignes ajoutées (vert) et supprimées (rouge)
- Commiter et pousser sans mémoriser de commandes
- Gérer plusieurs repos (gigarun-site, paperasse974…) depuis une seule fenêtre
- Accéder à l’historique complet des modifications avec l’auteur et le message
- Créer et changer de branche en un clic
📖 2. Le vocabulaire Git expliqué simplement
| Terme | Analogie simple | Ce que ça fait concrètement |
|---|---|---|
| Repository (repo) | Un dossier projet avec un historique complet | Contient tous les fichiers + tout l’historique des modifications depuis le début |
| Commit | Une sauvegarde nommée | Capture l’état des fichiers à un instant T avec un message explicatif. Irréversible dans l’historique. |
| Push | Envoyer vers le serveur | Envoie vos commits locaux vers GitHub.com pour que les autres puissent les voir |
| Pull / Fetch | Récupérer depuis le serveur | Fetch : télécharge les modifications sans les appliquer. Pull : télécharge ET applique. |
| Clone | Télécharger un repo complet | Copie un repo GitHub sur votre machine, avec tout l’historique |
| Fork | Faire sa propre copie d’un projet | Crée votre propre version d’un repo sur GitHub, indépendant de l’original. Ex : gigarun/paperasse974 est un fork de romainsimon/paperasse. |
| Branch (branche) | Une version parallèle du projet | Permet de travailler sur une fonctionnalité sans toucher au code principal (master/main) |
| Merge | Fusionner deux versions | Intègre les modifications d’une branche dans une autre |
| Upstream | Le repo original d’où vient le fork | Sur paperasse974 : l’upstream est romainsimon/paperasse. Permet de récupérer les mises à jour de l’auteur original. |
| Origin | Votre repo sur GitHub | Le serveur distant par défaut. Quand vous poussez, vous poussez vers origin. |
| Pull Request (PR) | Proposer ses modifications | Demande formelle d’intégration de vos modifications dans un autre repo (ex : soumettre la correction ZFANG à l’auteur original) |
| Conflict | Deux personnes ont modifié la même ligne | Git ne peut pas choisir automatiquement quelle version garder. Il faut résoudre manuellement. |
| Stash | Mettre de côté des modifications en cours | Sauvegarde temporairement les modifications non commitées pour changer de branche proprement |
| HEAD | Où vous êtes dans l’historique | Pointe vers le dernier commit de la branche active. « 5 commits ahead » = votre HEAD est 5 commits plus loin que l’upstream. |
| X commits ahead | Votre repo a des commits en plus | Votre fork a avancé par rapport à l’upstream — c’est normal et voulu quand vous avez ajouté vos personnalisations. |
| X commits behind | L’upstream a avancé sans vous | L’auteur original a publié des mises à jour que votre fork n’a pas encore. Action requise : fetch + merge upstream. |
⚙️ 3. Installation et connexion
-
Télécharger GitHub Desktop
Aller sur desktop.github.com → Download for Windows. Lancer l’installateur. L’application se met à jour automatiquement. -
Se connecter au compte
Au premier lancement : Sign in to GitHub.com → le navigateur s’ouvre → se connecter avec le compte gigarun → autoriser l’application → retourner dans GitHub Desktop. La connexion est retenue. -
Configurer l’identité Git
File → Options → Git : renseigner le nom et l’email. Ces informations apparaissent dans chaque commit de l’historique. -
Vérifier la connexion
File → Options → Accounts : le compte gigarun doit apparaître avec une icône verte.
GitHub Desktop gère l’authentification automatiquement via le navigateur. Le token personnel (ghp_xxx) n’est utile que pour les appels API directs ou les scripts PowerShell.
📥 4. Cloner un repo existant
Cloner = télécharger un repo GitHub sur votre machine pour pouvoir travailler dessus localement.
-
Ouvrir le dialogue de clonage
Menu File → Clone repository… (ou Ctrl+Shift+O) -
Choisir le repo
Onglet GitHub.com → les repos du compte gigarun apparaissent dans la liste. Chercher gigarun/paperasse974 ou gigarun/gigarun-site. -
Choisir le dossier de destination
Champ Local path : indiquer le chemin. Exemple :C:\Users\thoca\OneDrive - gigarun\PROJETS\paperasse974 -
Cliquer Clone
GitHub Desktop télécharge tous les fichiers et l’historique complet. Le repo apparaît ensuite dans la liste à gauche.
Toujours cloner dans C:\Users\thoca\OneDrive - gigarun\PROJETS\ pour que les fichiers soient synchronisés OneDrive. Exception : labs Docker et fichiers volumineux temporaires → C:\labs\ hors OneDrive.
🔄 5. Les 3 actions du quotidien
Action 1 — Voir et valider les modifications (Commit)
Dès qu’un fichier du repo est modifié (par vous, par Claude Code, peu importe), GitHub Desktop le détecte automatiquement.
M comptable/SKILL.md ← modifié
+ comptable/evals/evals.json ← ajouté
D ancien-fichier.md ← supprimé
Summary (required): [ Ajout ZFANG — régime dom 974 ]
Description: optionnel
Commit to master
- Panneau gauche : liste des fichiers modifiés. Cocher/décocher pour sélectionner ce qui fait partie du commit.
- Panneau droit : diff ligne par ligne. Vert = ajouté, rouge = supprimé.
- Champ Summary : message obligatoire, court, au présent. Ex : « Ajout TVA 8,5% DOM par défaut »
- Cliquer Commit to master : la modification est enregistrée localement dans l’historique.
Après un commit, les modifications sont enregistrées sur votre machine uniquement. GitHub.com ne voit rien encore. Il faut ensuite pousser (Push).
Action 2 — Envoyer vers GitHub (Push)
Après un ou plusieurs commits, la barre supérieure affiche le bouton Push origin avec le nombre de commits en attente.
Cliquer Push origin : les commits sont envoyés sur GitHub.com. Ils sont maintenant visibles sur github.com/gigarun/paperasse974.
Action 3 — Récupérer les mises à jour (Fetch / Pull)
Si quelqu’un d’autre (ou Claude Code depuis une autre machine) a pushé des modifications, il faut les récupérer.
- Fetch origin : vérifie s’il y a des nouveautés sur GitHub sans rien modifier localement.
- Pull origin : télécharge et applique les commits distants dans votre copie locale.
🔀 6. Gérer un fork et synchroniser avec l’upstream
Contexte : gigarun/paperasse974 est un fork de romainsimon/paperasse. Si l’auteur original publie des corrections ou de nouvelles fonctionnalités, il faut les récupérer dans notre fork sans écraser nos personnalisations (TVA 8,5%, ZFANG, evals).
Comprendre « X commits ahead / behind »
| Message | Signification | Action |
|---|---|---|
| 5 commits ahead | Votre fork a 5 commits de plus que l’upstream — vos personnalisations | Rien à faire, c’est voulu |
| 2 commits behind | L’upstream a publié 2 commits que votre fork n’a pas | Récupérer depuis l’upstream |
| 5 ahead, 2 behind | Les deux à la fois — situation courante | Merge upstream puis résoudre les conflits éventuels |
Procédure de synchronisation upstream
GitHub Desktop ne gère pas directement la synchronisation upstream via l’interface. On utilise un terminal intégré :
-
Ouvrir le terminal Git dans GitHub Desktop
Repository → Open in Command Prompt (ou PowerShell) -
Ajouter l’upstream (une seule fois)
PowerShell
git remote add upstream https://github.com/romainsimon/paperasse.git
# Si déjà fait, cette commande retourne une erreur inoffensive -
Récupérer les nouveautés de l’upstream
git fetch upstream
git merge upstream/master -
Vérifier dans GitHub Desktop
Les modifications upstream apparaissent dans l’historique. Si conflits : GitHub Desktop les signale en rouge → ouvrir les fichiers concernés, choisir quelle version garder, commiter la résolution. -
Pousser la synchro
Bouton Push origin dans GitHub Desktop pour que le fork sur GitHub.com soit à jour.
Les conflits potentiels sont sur comptable/SKILL.md et comptable/references/regional.md car nous les avons modifiés. En cas de conflit : toujours garder nos ajouts DOM/ZFANG et intégrer les corrections upstream.
🌳 7. Les branches — pourquoi et comment
Une branche est une ligne de développement isolée. On travaille dessus sans toucher au code principal (master). Une fois terminé, on fusionne (merge).
Quand créer une branche ?
- Pour tester une modification importante avant de la valider
- Pour préparer une Pull Request vers un repo externe
- Pour travailler sur deux fonctionnalités en parallèle
- Pas nécessaire pour des modifications simples sur un repo solo
Créer une branche dans GitHub Desktop
-
Cliquer sur le menu des branches
Barre du haut, deuxième menu : Current branch: master → cliquer dessus -
Créer la branche
New branch → nommer la branche (ex :fix-zfangoufeature-nouvelles-evals) → Create branch -
Travailler normalement
Tous les commits faits maintenant vont sur cette branche, pas sur master. -
Revenir sur master une fois terminé
Menu branches → master. Les fichiers redeviennent comme avant. -
Fusionner la branche dans master
Branch → Merge into current branch… → sélectionner votre branche → Merge.
Si vous êtes le seul à travailler sur un repo, les branches sont optionnelles pour les petites modifications. On commit directement sur master. Les branches deviennent utiles pour les gros chantiers ou les PR vers des repos extérieurs.
⚠️ 8. Pièges fréquents
Commit sans Push = modifications invisibles
Un commit local n’est pas automatiquement envoyé sur GitHub. Si vous fermez GitHub Desktop sans pousser, vos commits attendent. GitHub Desktop affiche le nombre de commits non pussés sur le bouton Push.
Modifier des fichiers sans commiter avant de changer de branche
Si vous changez de branche avec des modifications non commitées, Git vous propose de les emmener sur la nouvelle branche ou de les mettre en stash. En cas de doute, commiter d’abord.
Confondre Fetch et Pull
- Fetch = regarder sans toucher. Sûr.
- Pull = regarder ET appliquer. Peut créer des conflits si vous avez des modifications locales non pussées.
Bonne pratique : toujours faire un Push de vos modifications avant un Pull.
« 5 commits ahead » — pas un problème
Voir « X commits ahead of [upstream] » est normal quand votre fork a des personnalisations. Ce n’est pas une erreur, ce n’est pas quelque chose à corriger. C’est exactement l’état voulu.
Force Push — à éviter absolument
Le force push réécrit l’historique et peut détruire des commits irrécupérablement. GitHub Desktop ne propose pas cette option par défaut — c’est une protection. Si une commande demande --force, réfléchir deux fois.
Commiter des fichiers sensibles
Ne jamais commiter : mots de passe, tokens, fichiers .env, clés API. GitHub Desktop affiche tous les fichiers modifiés : avant de commiter, vérifier la liste. Un fichier .gitignore à la racine du repo liste les fichiers que Git ignore automatiquement.
✅ 9. Checklist de démarrage
- GitHub Desktop installé et connecté au compte gigarun
- Identité Git configurée (nom + email) dans File → Options → Git
- Repo gigarun/paperasse974 cloné dans
PROJETS\paperasse974 - Repo gigarun/gigarun-site cloné dans
PROJETS\gigarun-site - Premier commit test réalisé (modifier une ligne, commiter, pousser)
- Upstream papercasse ajouté en ligne de commande (
git remote add upstream ...) - Procédure Fetch/Merge upstream connue pour les futures mises à jour
Faire 3 commits réels sur un repo existant. La mécanique commit → push devient naturelle en 2-3 passages. Inutile de tout comprendre d’un coup — la pratique suffit.
Référence rapide — les raccourcis clavier
| Action | Raccourci |
|---|---|
| Commiter | Ctrl + Enter |
| Cloner un repo | Ctrl + Shift + O |
| Ouvrir dans l’explorateur | Ctrl + Shift + F |
| Ouvrir dans le terminal | Ctrl + ` |
| Historique des commits | Ctrl + 2 |
| Voir les changements en cours | Ctrl + 1 |
| Changer de repo | Ctrl + T |