Git : bonnes pratiques

Quelques habitudes rendent un historique lisible et un travail d’équipe fluide. Les exemples utilisent des valeurs génériques.

Des commits atomiques

Un commit représente un changement logique unique : il compile, passe les tests et se comprend seul. Ne pas mélanger correctif, refonte et mise à jour de configuration.

git add -p                          # choisir précisément les morceaux d'un commit
git add src/recherche.js
git commit -m "feat(search): add search endpoint"
git add package.json package-lock.json
git commit -m "build: update dependencies"

Avantages : revue plus simple, git revert ciblé, git bisect efficace, historique qui raconte l’histoire du projet.

Des messages clairs : Conventional Commits

Format type(portée): description à l’impératif, en minuscules, sans point final :

feat(auth): add password reset by email
fix(api): return 404 for unknown user
docs: update installation guide
refactor(db): extract query builder

Type	Usage
`feat`	Nouvelle fonctionnalité
`fix`	Correction de bug
`docs`	Documentation
`style`	Mise en forme (sans changement de comportement)
`refactor`	Réorganisation du code
`perf`	Amélioration de performance
`test`	Tests
`build`, `ci`, `chore`	Outils de compilation, intégration continue, maintenance

Un changement incompatible se signale par ! (feat(api)!: remove v1 endpoints) et un pied BREAKING CHANGE:. Un message de commit répond à « pourquoi » dans son corps quand c’est utile :

fix(cache): invalidate entries on user update

L'ancien cache servait des profils périmés jusqu'à une heure après une
modification, ce qui provoquait des affichages incohérents.

Des branches courtes et nommées

main toujours fonctionnelle et déployable.
Une branche par fonctionnalité ou correction : feat/recherche, fix/erreur-connexion.
Fusionner souvent : une branche qui vit des semaines diverge et génère des conflits.
Supprimer les branches fusionnées (git branch -d).

Synchroniser avant de travailler

git switch main
git pull --ff-only
git switch -c feat/recherche

Intégrer régulièrement main dans sa branche (git merge main ou git rebase main pour une branche personnelle) pour réduire les conflits.

Règles pour réécrire l’historique

Action	Autorisé si
`commit --amend`, `rebase -i`, `reset`	Les commits ne sont pas encore poussés
`push --force-with-lease`	La branche est personnelle
`revert`	Toujours (nouveau commit, aucun risque)
Réécrire `main`	Jamais

Protéger les secrets et les fichiers inutiles

Fichier .gitignore complet dès le premier commit (voir Premiers pas).
.env.example versionné (clés vides), .env ignoré.
Ne jamais valider de mot de passe, de clé ou de jeton. Si c’est arrivé : révoquer le secret (voir Annuler et corriger).

Un hook pre-commit anti-secrets

Les hooks sont des scripts exécutés automatiquement. Exemple de hook versionné dans le dépôt, .githooks/pre-commit :

#!/usr/bin/env bash
set -euo pipefail

# Refuse un fichier .env (sauf .env.example)
bad=$(git diff --cached --name-only --diff-filter=ACM | grep -E '(^|/)\.env($|\.)' | grep -vE '(^|/)\.env\.example$' || true)
if [[ -n "$bad" ]]; then
  echo "Commit refusé : fichier d'environnement indexé :" >&2
  echo "$bad" >&2
  exit 1
fi

# Refuse une clé privée dans le diff
if git diff --cached -U0 | grep -qE -e '-----BEGIN [A-Z ]*PRIVATE KEY-----'; then
  echo "Commit refusé : clé privée détectée dans le diff." >&2
  exit 1
fi

Activation (une fois par clone) :

chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

git commit --no-verify contourne le hook : à ne réserver qu’aux cas exceptionnels.

Protéger `main` sur le serveur

Sur le serveur Git (Gitea, GitHub, GitLab), activer la protection de branche pour main : interdire le push direct et le push forcé, exiger une demande de fusion relue et des tests réussis.

Fichiers volumineux

Git n’est pas adapté aux gros fichiers binaires (archives, vidéos, bases de données) : chaque version reste dans l’historique. Pour les gérer :

sudo apt install git-lfs
git lfs install
git lfs track "*.psd"
git add .gitattributes

Pour inspecter la taille d’un dépôt : git count-objects -vH.

Habitudes quotidiennes

git status                       # avant de commencer, et avant chaque commit
git diff --staged                # relire ce qui va être validé
git log --oneline --graph -10    # situer sa branche
git fetch --prune                # voir ce qui a changé sur le serveur

Pour aller plus loin

Spécification : conventionalcommits.org
Manuel : Git Hooks
Retour : Annuler et corriger