Fiche gitlab et git

Par /

1. Introduction

Dans un projet de BTS CIEL ou SIO, tu dois savoir organiser ton code, suivre tes modifications, collaborer avec d’autres personnes et retrouver rapidement l’historique d’un travail. Git répond à ce besoin en assurant le contrôle de version. GitLab ajoute une interface web pour héberger ton dépôt, gérer les branches, suivre les tâches, relire le code et préparer plus tard de l’intégration continue.

GitLab ne remplace pas Git. Git fonctionne sur ton poste. GitLab héberge le dépôt distant et facilite le travail en équipe. Dans GitLab, un dépôt appartient toujours à un projet. Le projet regroupe le code, les paramètres, les droits, les tickets, les merge requests et éventuellement les pipelines CI/CD.

L’objectif de cette fiche consiste à te rendre autonome sur un premier usage propre de GitLab : créer un projet depuis l’interface web, le récupérer sur ton PC, envoyer tes premiers fichiers, comprendre les commandes Git essentielles et mettre en place un fichier .gitignore.

2. Sommaire

  1. Introduction
  2. Sommaire
  3. Synthèse Markdown pour ta fiche bristol
  4. Principe général : Git, GitLab, dépôt local et dépôt distant
  5. Installation de Git sur Debian ou Ubuntu
  6. Configuration initiale de Git sur ton PC
  7. Création du projet GitLab depuis l’interface web
  8. Initialisation du projet sur le PC
  9. Arborescence recommandée d’un petit projet
  10. Fichier .gitignore : rôle, emplacement et exemples
  11. Configuration complète du fichier .gitignore
  12. Commandes Git de base à connaître
  13. Gestion des branches et merge requests
  14. Sécurité, droits d’accès, SSH et pare-feu
  15. Exemples concrets
  16. Commandes de vérification et dépannage
  17. Logs et diagnostic
  18. Erreurs fréquentes
  19. Conclusion orientée bonnes pratiques
  20. Pour aller plus loin
  21. Liens vers les sites officiels, MOOC et contenus pédagogiques
  22. Propositions de TP

3. Synthèse Markdown pour ta fiche bristol

# Fiche bristol — GitLab et Git

## Objectif
Git suit les versions du projet sur le PC.
GitLab héberge le dépôt distant et facilite le travail en équipe.

## Installation Debian/Ubuntu
sudo apt update
sudo apt install git

## Configuration utilisateur
git config --global user.name "Prénom Nom"
git config --global user.email "prenom.nom@example.com"
git config --global init.defaultBranch main

## Vérification
git --version
git config --global --list

## Cas 1 : récupérer un projet créé sur GitLab
git clone git@gitlab.com:utilisateur/mon-projet.git
cd mon-projet

## Cas 2 : initialiser un projet local existant
cd mon-projet
git init
git branch -M main
git remote add origin git@gitlab.com:utilisateur/mon-projet.git

## Cycle de travail classique
git status
git add .
git commit -m "Ajout de la première version"
git push -u origin main

## Mettre à jour le dépôt local
git pull

## Créer une branche
git switch -c feature/page-accueil

## Envoyer une branche vers GitLab
git push -u origin feature/page-accueil

## Voir l’historique
git log --oneline --graph --decorate --all

## .gitignore
Le fichier .gitignore indique à Git les fichiers à ne pas suivre :
- caches
- fichiers temporaires
- secrets
- dépendances générées
- fichiers propres à l’éditeur

4. Principe général : Git, GitLab, dépôt local et dépôt distant

Git fonctionne comme un carnet d’historique technique. À chaque étape importante, tu crées un commit. Ce commit contient une description courte et l’état des fichiers suivis par Git.

GitLab héberge une copie distante du projet. Cette copie distante permet de sauvegarder le travail, de collaborer et de centraliser les branches. La documentation GitLab rappelle que tu peux créer un projet depuis l’interface web ou envoyer un dépôt local avec git push.

Tu manipules donc généralement deux espaces :

  • le dépôt local : le dossier du projet sur ton PC ;
  • le dépôt distant : le projet hébergé sur GitLab.

Quand tu modifies ton code, Git ne l’envoie pas automatiquement sur GitLab. Tu dois ajouter les fichiers à l’index, créer un commit, puis pousser ce commit vers le dépôt distant. GitLab explique ce cycle dans sa documentation sur l’ajout, le commit et le push.

5. Installation de Git sur Debian ou Ubuntu

Sur Debian ou Ubuntu, tu installes Git avec apt. Cette méthode reste la plus simple pour un poste étudiant ou une VM de lab. Le site officiel de Git indique que les distributions Debian/Ubuntu utilisent le gestionnaire de paquets pour installer Git.

sudo apt update
sudo apt install git

La commande sudo apt update met à jour la liste locale des paquets disponibles. Elle ne met pas encore à jour les logiciels installés. Elle permet simplement à ton système de connaître les versions disponibles dans les dépôts configurés.

La commande sudo apt install git installe Git et ses dépendances. Le paquet git suffit pour les usages classiques : clone, commit, push, pull, branches et historique.

Tu peux ensuite vérifier l’installation.

git --version

Cette commande affiche la version de Git installée. Elle confirme que le binaire git existe bien dans le système.

Sur un poste Debian/Ubuntu, tu n’as pas besoin d’installer GitLab sur ton PC pour utiliser GitLab.com ou un GitLab d’établissement. Tu utilises Git en local et tu échanges avec GitLab via HTTPS ou SSH.

6. Configuration initiale de Git sur ton PC

Avant le premier commit, tu dois configurer ton nom et ton adresse e-mail. Git inscrit ces informations dans l’historique des commits. Cette configuration ne crée pas de compte GitLab. Elle identifie simplement l’auteur des commits sur ton poste.

git config --global user.name "Prénom Nom"
git config --global user.email "prenom.nom@example.com"
git config --global init.defaultBranch main

La commande git config modifie les paramètres Git.

L’option --global applique le réglage à ton utilisateur Linux. Git stocke alors ces paramètres dans le fichier ~/.gitconfig.

Le paramètre user.name définit le nom affiché dans l’historique des commits.

Le paramètre user.email définit l’adresse e-mail associée aux commits. Utilise de préférence la même adresse que celle de ton compte GitLab.

Le paramètre init.defaultBranch main indique à Git de créer par défaut une branche principale appelée main lors d’un git init.

Tu peux vérifier la configuration.

git config --global --list

Cette commande affiche les paramètres Git globaux. L’option --list demande à Git de lister les clés configurées.

7. Création du projet GitLab depuis l’interface web

Commence par créer le projet dans GitLab. Cette méthode reste très pédagogique, car tu vois clairement où se situe le dépôt distant.

Dans l’interface GitLab :

  1. Connecte-toi à GitLab.
  2. Clique sur Create new.
  3. Choisis New project/repository.
  4. Sélectionne Create blank project.
  5. Renseigne le nom du projet, par exemple bts-gitlab-demo.
  6. Vérifie le slug du projet, par exemple bts-gitlab-demo.
  7. Choisis la visibilité :
    • Private pour un projet personnel ou scolaire ;
    • Internal seulement dans une instance GitLab interne ;
    • Public uniquement si le contenu peut être visible par tous.
  8. Coche éventuellement Initialize repository with a README.
  9. Ajoute un template .gitignore si GitLab te le propose et si ton langage correspond.
  10. Clique sur Create project.

GitLab documente cette création de projet depuis l’interface web, avec les étapes de création d’un projet vide ou depuis un modèle.

Pour un premier TP, coche Initialize repository with a README. GitLab crée alors un premier fichier README.md. Ce choix simplifie le clonage, car le dépôt distant n’est pas vide.

8. Initialisation du projet sur le PC

Tu as deux cas fréquents.

8.1. Cas recommandé pour débuter : cloner le projet créé sur GitLab

Après la création du projet, GitLab affiche une adresse de clonage. Privilégie SSH si tu as configuré une clé SSH. Sinon, tu peux utiliser HTTPS.

Exemple avec SSH :

git clone git@gitlab.com:utilisateur/bts-gitlab-demo.git
cd bts-gitlab-demo

La commande git clone télécharge le dépôt distant sur ton PC. Elle crée un dossier local, récupère l’historique et configure automatiquement le lien vers GitLab.

La commande cd bts-gitlab-demo entre dans le dossier du projet.

Tu peux vérifier le dépôt distant.

git remote -v

La commande git remote -v affiche les dépôts distants connus. Le nom origin désigne généralement le dépôt GitLab principal. L’option -v affiche les URL utilisées pour lire et écrire.

8.2. Cas d’un dossier local déjà existant

Tu peux aussi partir d’un dossier déjà présent sur ton PC.

mkdir bts-gitlab-demo
cd bts-gitlab-demo
git init
git branch -M main
git remote add origin git@gitlab.com:utilisateur/bts-gitlab-demo.git

La commande mkdir bts-gitlab-demo crée un nouveau dossier.

La commande cd bts-gitlab-demo te place dans ce dossier.

La commande git init transforme ce dossier en dépôt Git local. Git crée alors le dossier caché .git.

La commande git branch -M main renomme la branche courante en main. L’option -M force le renommage si nécessaire.

La commande git remote add origin ... ajoute le dépôt distant GitLab. Le nom origin reste une convention très courante.

Tu peux ensuite créer un premier fichier.

echo "# BTS GitLab Demo" > README.md
git status
git add README.md
git commit -m "Ajout du README initial"
git push -u origin main

La commande echo "# BTS GitLab Demo" > README.md crée un fichier Markdown simple.

La commande git status affiche l’état du dépôt : fichiers modifiés, fichiers non suivis, branche courante.

La commande git add README.md ajoute le fichier à l’index. Git prépare alors ce fichier pour le prochain commit.

La commande git commit -m "Ajout du README initial" crée un commit avec un message. L’option -m permet d’écrire le message directement dans la commande.

La commande git push -u origin main envoie la branche main vers GitLab. L’option -u associe la branche locale à la branche distante. Après ce premier push, un simple git push suffit généralement.

9. Arborescence recommandée d’un petit projet

Voici une arborescence simple pour un projet de cours, de script ou de mini-application.

bts-gitlab-demo/
├── .git/
├── .gitignore
├── README.md
├── docs/
│   └── installation.md
├── src/
│   └── main.py
├── tests/
│   └── test_main.py
└── scripts/
    └── demo.sh

Le dossier .git/ contient l’historique local du dépôt. Tu ne le modifies jamais à la main.

Le fichier .gitignore liste les fichiers que Git doit ignorer.

Le fichier README.md présente le projet, l’installation, l’usage et les commandes utiles.

Le dossier docs/ contient la documentation.

Le dossier src/ contient le code source.

Le dossier tests/ contient les tests.

Le dossier scripts/ contient les scripts utiles au projet.

Cette organisation reste simple, lisible et adaptée à un projet BTS.

10. Fichier .gitignore : rôle, emplacement et exemples

Le fichier .gitignore sert à éviter d’envoyer dans Git des fichiers inutiles ou sensibles. La documentation officielle de Git précise qu’un fichier .gitignore définit des fichiers volontairement non suivis, mais qu’il ne s’applique pas aux fichiers déjà suivis par Git.

Tu places généralement .gitignore à la racine du projet.

Exemples de fichiers à ignorer :

  • fichiers temporaires de l’éditeur ;
  • caches Python ;
  • dossier node_modules/ ;
  • fichiers .env contenant des secrets ;
  • fichiers de logs locaux ;
  • archives générées ;
  • répertoires de build.

Attention : .gitignore ne protège pas un secret déjà envoyé dans Git. Si tu as déjà commité un mot de passe, tu dois le révoquer et nettoyer l’historique si nécessaire.

11. Configuration complète du fichier .gitignore

Ce bloc propose un fichier .gitignore complet et adapté à un projet pédagogique Debian/Ubuntu avec scripts, Python, Node.js éventuel et documentation. Tu peux le placer dans un bloc de code WordPress.

# =====================================================
# .gitignore — projet GitLab / BTS CIEL-SIO
# Emplacement recommandé : racine du projet
# Exemple : /home/etudiant/projets/bts-gitlab-demo/.gitignore
# =====================================================

# -----------------------------------------------------
# 1. Système d'exploitation
# -----------------------------------------------------
.DS_Store
Thumbs.db
desktop.ini

# -----------------------------------------------------
# 2. Éditeurs et IDE
# -----------------------------------------------------
.vscode/
.idea/
*.swp
*.swo
*~

# -----------------------------------------------------
# 3. Python
# -----------------------------------------------------
__pycache__/
*.py[cod]
*.pyo
*.pyd
.venv/
venv/
env/
pip-wheel-metadata/
.pytest_cache/
.coverage
htmlcov/

# -----------------------------------------------------
# 4. Node.js / JavaScript
# -----------------------------------------------------
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
dist/
build/

# -----------------------------------------------------
# 5. Variables d'environnement et secrets
# -----------------------------------------------------
.env
.env.*
!.env.example
secrets/
*.key
*.pem
*.p12
*.crt

# -----------------------------------------------------
# 6. Logs locaux
# -----------------------------------------------------
logs/
*.log

# -----------------------------------------------------
# 7. Archives et fichiers générés
# -----------------------------------------------------
*.zip
*.tar
*.tar.gz
*.tgz
*.7z
*.bak
*.tmp

# -----------------------------------------------------
# 8. Fichiers de bases de données locales
# -----------------------------------------------------
*.sqlite
*.sqlite3
*.db

# -----------------------------------------------------
# 9. WordPress local éventuel
# -----------------------------------------------------
wp-config.php
wp-content/uploads/
wp-content/cache/

La ligne .env ignore les fichiers de variables d’environnement. Ces fichiers contiennent souvent des mots de passe, des tokens ou des URL internes.

La ligne !.env.example force Git à suivre un fichier d’exemple. Tu peux y mettre les noms des variables sans les vraies valeurs.

La ligne node_modules/ ignore les dépendances Node.js. Tu ne dois pas versionner ce dossier, car tu peux le reconstruire avec npm install.

La ligne __pycache__/ ignore le cache Python généré automatiquement.

La ligne wp-config.php protège un fichier WordPress qui contient les accès à la base de données.

12. Commandes Git de base à connaître

GitLab maintient une page de référence sur les commandes Git courantes. Cette page couvre les usages essentiels comme les changements, les branches, les commits et l’historique.

12.1. Voir l’état du dépôt

git status

Cette commande affiche les fichiers modifiés, les fichiers ajoutés à l’index et les fichiers non suivis. Utilise-la très souvent. Elle évite beaucoup d’erreurs.

12.2. Ajouter un fichier précis

git add README.md

La commande git add place un fichier dans l’index. Git prendra ce fichier en compte dans le prochain commit.

Tu peux remplacer README.md par un autre chemin, par exemple src/main.py.

12.3. Ajouter tous les fichiers modifiés

git add .

Le point . désigne le dossier courant. Cette commande ajoute tous les fichiers modifiés ou nouveaux sous ce dossier.

Utilise-la avec prudence. Vérifie toujours avec git status avant de créer le commit.

12.4. Créer un commit

git commit -m "Ajout de la structure initiale du projet"

La commande git commit enregistre une version du projet dans l’historique local.

L’option -m permet d’écrire le message du commit directement. Le message doit expliquer ce que tu as changé.

Un bon message reste court et précis. Par exemple : Ajout du .gitignore Python ou Correction du script de sauvegarde.

12.5. Envoyer les commits vers GitLab

git push

La commande git push envoie tes commits locaux vers le dépôt distant GitLab.

Lors du premier envoi d’une branche, tu peux utiliser :

git push -u origin main

L’option -u configure le suivi entre la branche locale et la branche distante. Ensuite, git push suffit.

12.6. Récupérer les changements depuis GitLab

git pull

La commande git pull récupère les changements distants et les intègre dans ta branche locale.

Tu l’utilises quand un collègue a poussé du code ou quand tu travailles sur plusieurs postes.

12.7. Voir l’historique

git log --oneline --graph --decorate --all

La commande git log affiche l’historique.

L’option --oneline affiche chaque commit sur une ligne.

L’option --graph montre les branches sous forme graphique dans le terminal.

L’option --decorate affiche les noms de branches et de tags.

L’option --all affiche toutes les branches connues.

12.8. Voir les différences avant commit

git diff

Cette commande affiche les différences entre les fichiers modifiés et le dernier commit.

Pour voir les différences déjà ajoutées à l’index, utilise :

git diff --staged

L’option --staged indique à Git de comparer ce qui se trouve dans l’index avec le dernier commit.

12.9. Retirer un fichier de l’index sans le supprimer

git restore --staged fichier.txt

Cette commande enlève fichier.txt de l’index. Elle ne supprime pas le fichier du disque.

Tu l’utilises quand tu as fait un git add trop large.

12.10. Annuler une modification locale non commitée

git restore fichier.txt

Cette commande remet fichier.txt dans l’état du dernier commit.

Attention : elle supprime tes modifications locales sur ce fichier. Utilise git diff avant.

13. Gestion des branches et merge requests

Une branche permet de travailler sur une évolution sans modifier directement la branche principale main.

13.1. Créer une branche

git switch -c feature/page-accueil

La commande git switch change de branche.

L’option -c crée une nouvelle branche et bascule dessus.

Le nom feature/page-accueil indique que la branche correspond à une nouvelle fonctionnalité.

Tu peux aussi rencontrer l’ancienne commande :

git checkout -b feature/page-accueil

Elle fonctionne encore, mais git switch rend l’intention plus claire pour débuter.

13.2. Envoyer une branche vers GitLab

git push -u origin feature/page-accueil

Cette commande pousse la branche vers GitLab.

L’option -u associe la branche locale à la branche distante.

Après ce push, GitLab propose souvent de créer une merge request.

13.3. Comprendre la merge request

Une merge request sert à demander l’intégration d’une branche dans une autre branche, souvent vers main.

Dans GitLab, elle permet :

  • de relire le code ;
  • de discuter des changements ;
  • de vérifier les conflits ;
  • de déclencher des contrôles CI/CD si le projet les configure ;
  • de garder une trace de la décision.

Pour un projet BTS, tu peux utiliser une merge request même seul. Elle t’aide à documenter proprement ton travail.

14. Sécurité, droits d’accès, SSH et pare-feu

14.1. Utiliser SSH plutôt que le mot de passe

GitLab recommande l’usage des clés SSH : tu génères une paire de clés sur ton poste, tu ajoutes la clé publique dans ton compte GitLab, puis tu vérifies la connexion.

Génère une clé SSH moderne avec ed25519.

ssh-keygen -t ed25519 -C "prenom.nom@example.com"

La commande ssh-keygen crée une paire de clés.

L’option -t ed25519 choisit l’algorithme Ed25519, adapté aux usages modernes.

L’option -C ajoute un commentaire. Tu peux mettre ton adresse e-mail pour reconnaître la clé dans GitLab.

Par défaut, Git propose le fichier :

~/.ssh/id_ed25519

Le fichier ~/.ssh/id_ed25519 contient la clé privée. Tu ne dois jamais la partager.

Le fichier ~/.ssh/id_ed25519.pub contient la clé publique. Tu peux la copier dans GitLab.

Affiche la clé publique.

cat ~/.ssh/id_ed25519.pub

La commande cat affiche le contenu du fichier. Copie toute la ligne dans GitLab, dans les paramètres SSH de ton compte.

Teste ensuite la connexion.

ssh -T git@gitlab.com

La commande ssh ouvre une connexion SSH.

L’option -T désactive l’ouverture d’un terminal distant. Pour GitLab, tu veux seulement vérifier l’authentification Git.

14.2. Ports réseau concernés

Quand tu utilises GitLab.com ou un GitLab hébergé

Retour en haut