Skip to content

madjeek-web/GITHUB-GUIDE

BranchesTags

Repository files navigation

License: MIT GitHub stars GitHub last commit Maintained GitHub forks PRs Welcome

GITHUB-GUIDE

Guide complet Git et GitHub pour débutants et développeurs juniors. Complete Git and GitHub guide for beginners and junior developers.

Lire en français : Section française
Read in English : English section

Table des matières / Table of Contents

Français

English

Version Française

A propos de ce guide

Ce guide s'adresse aux personnes qui débutent en informatique, aux étudiants en première année de développement, et à toute personne souhaitant comprendre Git et GitHub de façon concrète et progressive. Aucune connaissance préalable n'est requise pour commencer.

Git est un outil de gestion de version. GitHub est une plateforme en ligne qui héberge des dépôts Git. Les deux ne sont pas la même chose, mais ils fonctionnent ensemble. Ce guide vous explique comment les utiliser efficacement, depuis l'installation jusqu'aux pratiques professionnelles.

Cheat sheet visuelle (image) disponible dans ce dépôt :

GitHub Cheat Sheet

Cheat sheet PDF téléchargeable : Git-Cheat-Sheet_FR.pdf

Prérequis

Avant de commencer, vous avez besoin de :

Comprendre Git et GitHub

Git est un logiciel libre installé localement sur votre ordinateur. Il permet de suivre l'historique de vos fichiers, de travailler sur plusieurs versions en parallèle et de revenir en arrière si besoin.

GitHub est un site web qui héberge vos dépôts Git en ligne. Il permet de collaborer avec d'autres personnes, de rendre votre code public ou privé, et d'utiliser des outils comme les Issues, les Pull Requests ou les GitHub Actions.

Concept Git GitHub
Type Logiciel local Plateforme en ligne
Rôle Gestion de version Hébergement et collaboration
Fonctionne sans internet Oui Non
Gratuit Oui Oui (avec options payantes)

Autres alternatives à GitHub (si vous êtes curieux) :

  • GitLab : similaire à GitHub, très utilisé en entreprise
  • Bitbucket : utilisé souvent avec les outils Atlassian

Installation et configuration

Installer Git

Rendez-vous sur https://git-scm.com/downloads et téléchargez la version correspondant à votre système d'exploitation (Windows, macOS, Linux).

Vérifiez l'installation en ouvrant un terminal et en tapant :

git --version

Vous devriez voir quelque chose comme git version 2.43.0.

Configurer votre identité

Avant d'utiliser Git, vous devez indiquer votre nom et votre adresse e-mail. Ces informations apparaîtront dans chaque commit que vous créerez.

git config --global user.name "Votre Nom"
git config --global user.email "votre@email.com"

Configurer l'éditeur par défaut (optionnel)

# Pour utiliser Visual Studio Code comme éditeur Git
git config --global core.editor "code --wait"

# Pour utiliser nano (plus simple en terminal)
git config --global core.editor "nano"

Vérifier votre configuration

git config --list

Configurer l'authentification SSH (recommandé)

L'authentification SSH est plus sécurisée et plus pratique que le mot de passe. Elle vous évite de saisir vos identifiants à chaque opération.

# Générer une clé SSH
ssh-keygen -t ed25519 -C "votre@email.com"

# Afficher la clé publique à copier dans GitHub
cat ~/.ssh/id_ed25519.pub

Ensuite, allez dans GitHub > Settings > SSH and GPG keys > New SSH key et collez votre clé.

Documentation officielle SSH : https://docs.github.com/fr/authentication/connecting-to-github-with-ssh

Structure d'un dépôt professionnel

Une bonne structure de dépôt facilite la lecture, la maintenance et la collaboration. Voici la structure recommandée, utilisée dans la majorité des projets professionnels :

mon-projet/
├── .github/
│   ├── workflows/            # Fichiers GitHub Actions (CI/CD)
│   │   └── ci.yml
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── PULL_REQUEST_TEMPLATE.md
├── docs/                     # Documentation détaillée
│   └── architecture.md
├── src/                      # Code source principal
│   ├── main/                 # Code de production
│   └── test/                 # Tests automatisés
├── scripts/                  # Scripts utilitaires
├── img/                      # Images du projet (captures, logos, cheat sheets...)
├── build/                    # Fichiers de compilation (souvent dans .gitignore)
├── dist/                     # Fichiers distribuables (optionnel)
├── .gitignore                # Fichiers à ignorer dans Git
├── .editorconfig             # Configuration de l'éditeur
├── LICENSE                   # Licence du projet
├── README.md                 # Fichier principal de présentation
├── CONTRIBUTING.md           # Guide de contribution
├── CHANGELOG.md              # Historique des changements
├── SECURITY.md               # Politique de sécurité
└── CODE_OF_CONDUCT.md        # Code de conduite

Rôle de chaque élément

Le dossier .github/

Ce dossier est reconnu automatiquement par GitHub. Il contient la configuration propre à la plateforme. Le sous-dossier workflows/ contient les automatisations (CI/CD). Le sous-dossier ISSUE_TEMPLATE/ contient les modèles de tickets. Le fichier PULL_REQUEST_TEMPLATE.md est le modèle affiché quand quelqu'un ouvre une Pull Request.

Le dossier docs/

La documentation détaillée du projet : architecture, décisions techniques, guides d'utilisation, spécifications. Ce dossier peut aussi alimenter GitHub Pages pour générer un site web statique.

Le dossier src/

Le code source de l'application. Il est classique de séparer main/ (code de production) et test/ (tests).

Le dossier scripts/

Scripts d'automatisation, de déploiement, d'analyse ou de maintenance.

Les fichiers racine

Ces fichiers sont placés à la racine car GitHub les reconnaît et les affiche automatiquement.

Créer sa structure depuis l'interface web GitHub

Cette méthode est idéale si vous débutez ou si vous n'avez pas encore Git installé localement.

Etape 1 : Créer un nouveau dépôt

  1. Allez sur https://github.com/new
  2. Remplissez le nom du dépôt
  3. Ajoutez une description courte
  4. Choisissez Public ou Private
  5. Cochez "Add a README file"
  6. Choisissez un fichier .gitignore selon votre langage
  7. Choisissez une licence (MIT pour commencer)
  8. Cliquez sur "Create repository"

Etape 2 : Créer des fichiers et dossiers

Pour créer un fichier dans un dossier qui n'existe pas encore, cliquez sur "Add file" > "Create new file" et tapez directement le chemin avec le /. Par exemple, entrez docs/architecture.md pour créer le fichier architecture.md dans le dossier docs/.

GitHub crée automatiquement les dossiers intermédiaires.

Etape 3 : Ajouter un fichier CONTRIBUTING.md

Cliquez sur "Add file" > "Create new file" et nommez-le CONTRIBUTING.md.

Etape 4 : Créer les templates d'issues

Cliquez sur "Add file" > "Create new file" et entrez le chemin .github/ISSUE_TEMPLATE/bug_report.md.

Etape 5 : Configurer GitHub Actions

Cliquez sur "Add file" > "Create new file" et entrez .github/workflows/ci.yml.

Etape 6 : Configurer les labels

Dans l'onglet "Issues", cliquez sur "Labels" pour gérer vos labels. Les labels recommandés sont :

Label Description
bug Quelque chose ne fonctionne pas
enhancement Nouvelle fonctionnalité
documentation Amélioration de la documentation
good first issue Idéal pour une première contribution
help wanted Aide externe souhaitée
question Demande d'information
wontfix Ce problème ne sera pas traité
duplicate Ce problème a déjà été signalé

Créer sa structure depuis la ligne de commande

Initialiser un nouveau projet

# Créer le dossier du projet et entrer dedans
mkdir mon-projet
cd mon-projet

# Initialiser le dépôt Git
git init

Créer la structure complète en une seule commande

mkdir -p .github/{workflows,ISSUE_TEMPLATE} docs src/{main,test} scripts img build dist

Créer les fichiers de base

touch .gitignore LICENSE README.md CONTRIBUTING.md CHANGELOG.md SECURITY.md CODE_OF_CONDUCT.md
touch .github/PULL_REQUEST_TEMPLATE.md
touch .github/ISSUE_TEMPLATE/bug_report.md
touch .github/ISSUE_TEMPLATE/feature_request.md
touch .github/workflows/ci.yml
touch docs/architecture.md

Créer un .gitignore complet

cat > .gitignore << 'EOF'
# Dépendances
node_modules/
vendor/
.venv/

# Build
build/
dist/
*.class
*.jar
*.war
*.ear

# Logs
*.log
*.tmp
*.swp

# Environnement
.env
.env.local
.env.production

# IDE
.idea/
*.iml
.vscode/
*.suo
*.ntvs*
*.njsproj
*.sln

# OS
.DS_Store
Thumbs.db

# Tests
coverage/
.nyc_output/
EOF

Effectuer le premier commit

# Ajouter tous les fichiers
git add .

# Créer le premier commit
git commit -m "feat: initial project structure"

# Connecter au dépôt GitHub (remplacez avec votre URL)
git remote add origin git@github.com:votre-utilisateur/mon-projet.git

# Envoyer sur GitHub
git push -u origin main

Commandes Git essentielles

Pour la documentation complète et toujours à jour : https://git-scm.com/docs

Initialiser et cloner

# Initialiser un dépôt dans le dossier courant
git init

# Cloner un dépôt distant
git clone https://github.com/utilisateur/depot.git

# Cloner dans un dossier avec un nom spécifique
git clone https://github.com/utilisateur/depot.git mon-dossier

Etat et historique

# Voir l'état du dépôt (fichiers modifiés, staged, etc.)
git status

# Voir l'historique des commits
git log

# Voir l'historique de façon compacte
git log --oneline

# Voir l'historique avec représentation graphique des branches
git log --oneline --graph --all

# Voir les différences entre le working directory et le staging
git diff

# Voir les différences pour les fichiers staged
git diff --staged

Ajouter et commiter

# Ajouter un fichier au staging
git add nom-du-fichier.txt

# Ajouter tous les fichiers modifiés
git add .

# Créer un commit
git commit -m "message de commit"

# Ajouter et commiter en une commande (fichiers déjà trackés uniquement)
git commit -am "message de commit"

# Modifier le message du dernier commit (avant push uniquement)
git commit --amend -m "nouveau message"

Branches

# Lister les branches locales
git branch

# Lister toutes les branches (locales et distantes)
git branch -a

# Créer une nouvelle branche
git branch nom-de-branche

# Passer sur une branche existante
git checkout nom-de-branche

# Créer une branche et y passer directement (recommandé)
git checkout -b nom-de-branche

# Méthode moderne (Git 2.23+)
git switch -c nom-de-branche

# Supprimer une branche locale
git branch -d nom-de-branche

# Forcer la suppression d'une branche locale
git branch -D nom-de-branche

Synchroniser avec le dépôt distant

# Récupérer les changements distants sans fusionner
git fetch

# Récupérer et fusionner les changements distants
git pull

# Envoyer les commits sur le dépôt distant
git push

# Premier push d'une branche
git push -u origin nom-de-branche

# Supprimer une branche distante
git push origin --delete nom-de-branche

Fusionner et rebaser

# Fusionner une branche dans la branche courante
git merge nom-de-branche

# Rebaser la branche courante sur une autre
git rebase main

# Annuler un merge en cours
git merge --abort

# Annuler un rebase en cours
git rebase --abort

Stash (remiser temporairement)

# Mettre de côté les modifications en cours
git stash

# Lister les stash
git stash list

# Réappliquer le dernier stash
git stash pop

# Réappliquer sans supprimer le stash
git stash apply

Tags

# Créer un tag sur le commit courant
git tag v1.0.0

# Créer un tag annoté (recommandé pour les releases)
git tag -a v1.0.0 -m "Version 1.0.0"

# Lister les tags
git tag

# Pousser les tags vers GitHub
git push origin --tags

Revenir en arrière

# Désindexer un fichier (enlever du staging)
git reset HEAD nom-du-fichier.txt

# Annuler les modifications d'un fichier (revenir à la version committée)
git checkout -- nom-du-fichier.txt

# Revenir au commit précédent (sans effacer l'historique)
git revert HEAD

# Réinitialiser au commit d'un certain hash (dangereux, modifie l'historique)
git reset --hard abc1234

Branches et workflow

Le modèle Git Flow

Git Flow est une convention d'organisation des branches qui structure le travail en équipe. Ce n'est pas une obligation, mais c'est une bonne référence pour les projets professionnels.

Branche Rôle
main Version stable en production
develop Développement en cours, intégration
feature/nom Développement d'une nouvelle fonctionnalité
fix/nom Correction de bug
hotfix/nom Correction urgente en production
release/1.0.0 Préparation d'une version

Workflow type pour une fonctionnalité

# Partir toujours depuis develop à jour
git checkout develop
git pull

# Créer la branche de fonctionnalité
git checkout -b feature/ma-fonctionnalite

# ... travailler, commiter ...

# Mettre à jour par rapport à develop avant de merger
git fetch origin
git rebase origin/develop

# Ouvrir une Pull Request sur GitHub depuis feature/ma-fonctionnalite vers develop

Pull Requests

Une Pull Request (PR) est une demande d'intégration de votre branche dans une autre. C'est le coeur du travail collaboratif sur GitHub. Elle permet à l'équipe de relire le code, de faire des commentaires, et de valider les changements avant qu'ils n'arrivent sur la branche principale.

Bonnes pratiques pour une Pull Request :

  • Donner un titre clair et descriptif
  • Décrire ce que fait le changement et pourquoi
  • Référencer les issues liées avec Closes #42 ou Fixes #42
  • Garder la PR aussi petite et ciblée que possible
  • Répondre aux commentaires de revue de façon constructive

Messages de commit

Un bon message de commit explique clairement ce qui a été fait et pourquoi. La convention la plus répandue est Conventional Commits : https://www.conventionalcommits.org/fr/

Format

type(scope): description courte

Corps optionnel : explication plus détaillée.

Footer optionnel : références aux issues, breaking changes...

Types de commit

Type Utilisation
feat Nouvelle fonctionnalité
fix Correction de bug
docs Modification de documentation
style Formatage, espaces (pas de changement de logique)
refactor Refactoring sans changement de comportement
test Ajout ou modification de tests
chore Tâches de maintenance, dépendances
perf Amélioration de performance
ci Changements liés à l'intégration continue
build Changements de build system
revert Annulation d'un commit précédent

Exemples

feat(auth): add email verification on registration

fix(api): correct HTTP status code on 404 responses

docs: update installation steps in README

chore(deps): update dependencies to latest versions

feat(user): add profile picture upload

Closes #42

GitHub Actions et CI/CD

GitHub Actions est le système d'automatisation intégré à GitHub. Il permet de déclencher des actions automatiques sur des événements (push, pull request, déploiement, etc.).

Documentation officielle : https://docs.github.com/fr/actions

Exemple de workflow CI basique

Ce fichier doit être placé dans .github/workflows/ci.yml :

name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout du code
        uses: actions/checkout@v4

      - name: Configurer Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Installer les dépendances
        run: npm install

      - name: Lancer les tests
        run: npm test

      - name: Vérifier le style de code
        run: npm run lint

Exemple pour un projet PHP/Symfony

name: CI PHP

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Configurer PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Installer les dépendances Composer
        run: composer install

      - name: Lancer PHPStan
        run: vendor/bin/phpstan analyse

      - name: Lancer les tests PHPUnit
        run: vendor/bin/phpunit

Principaux déclencheurs (triggers)

Déclencheur Description
push A chaque push sur une branche
pull_request A l'ouverture ou la mise à jour d'une PR
schedule Selon un planning cron
workflow_dispatch Déclenchement manuel
release A la création d'une release

Contribuer à un projet open source

L'open source est au coeur de l'écosystème du développement. Contribuer à un projet existant est une excellente façon d'apprendre, de se faire connaître et de donner en retour à la communauté.

Guide officiel GitHub sur les contributions : https://docs.github.com/fr/get-started/exploring-projects-on-github/contributing-to-a-project

Etapes pour contribuer

1. Trouver un projet

2. Forker le dépôt

Le fork crée une copie du dépôt sur votre compte GitHub. Cliquez sur le bouton "Fork" en haut à droite de la page du projet.

3. Cloner votre fork

git clone git@github.com:votre-utilisateur/le-projet.git
cd le-projet

4. Ajouter le dépôt original comme remote

git remote add upstream git@github.com:auteur-original/le-projet.git

5. Créer une branche pour votre contribution

git checkout -b feature/ma-contribution

6. Faire vos modifications et commiter

git add .
git commit -m "feat: add my contribution"

7. Mettre à jour votre fork avec les dernières modifications de l'original

git fetch upstream
git rebase upstream/main

8. Pousser et ouvrir une Pull Request

git push origin feature/ma-contribution

Ensuite allez sur GitHub et ouvrez une Pull Request depuis votre branche vers la branche principale du projet original.

9. Répondre aux retours

Le mainteneur du projet relira votre code et pourra demander des modifications. Restez ouvert aux retours, c'est normal et constructif.

Points d'attention

  • Lisez toujours le fichier CONTRIBUTING.md avant de commencer
  • Vérifiez qu'il n'existe pas déjà une issue ou une PR pour ce que vous voulez faire
  • Respectez le style de code du projet
  • Ecrivez des tests si le projet en a
  • Soyez patient : les mainteneurs sont souvent bénévoles

Fichiers importants d'un dépôt

Fichier Rôle Obligatoire
README.md Présentation du projet Fortement recommandé
LICENSE Licence d'utilisation Oui pour l'open source
CONTRIBUTING.md Guide de contribution Recommandé
CHANGELOG.md Historique des versions Recommandé
SECURITY.md Comment signaler une faille Recommandé
CODE_OF_CONDUCT.md Règles de comportement Recommandé
.gitignore Fichiers ignorés par Git Oui
.editorconfig Config de l'éditeur pour tous Optionnel

Les licences les plus courantes

Licence Utilisation Lien
MIT Très permissive, usage libre opensource.org/licenses/MIT
Apache 2.0 Permissive, mention de brevets apache.org/licenses/LICENSE-2.0
GPL v3 Copyleft, le code dérivé doit rester libre gnu.org/licenses/gpl-3.0
AGPL v3 Comme GPL mais aussi pour les services web gnu.org/licenses/agpl-3.0
LGPL Permissive pour les bibliothèques gnu.org/licenses/lgpl-3.0
ISC Similaire à MIT, très courte opensource.org/licenses/ISC

Outil pour choisir une licence : https://choosealicense.com/

Badges GitHub

Les badges sont de petites images affichées dans le README. Ils communiquent des informations importantes en un coup d'oeil : statut de build, version, licence, couverture de tests...

Générateur de badges : https://shields.io/

Badges courants

# Statut de CI
[![CI](https://github.com/utilisateur/depot/actions/workflows/ci.yml/badge.svg)](https://github.com/utilisateur/depot/actions)

# Licence
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# Version
[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/utilisateur/depot/releases)

# Couverture de tests
[![Coverage](https://img.shields.io/codecov/c/github/utilisateur/depot)](https://codecov.io/gh/utilisateur/depot)

# PRs bienvenues
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

# Stars GitHub
[![GitHub stars](https://img.shields.io/github/stars/utilisateur/depot?style=social)](https://github.com/utilisateur/depot/stargazers)

# Dernière version publiée
[![GitHub release](https://img.shields.io/github/v/release/utilisateur/depot)](https://github.com/utilisateur/depot/releases)

# Dernier commit
[![GitHub last commit](https://img.shields.io/github/last-commit/utilisateur/depot)](https://github.com/utilisateur/depot/commits/main)

Ressources et liens

Documentation officielle

Syntaxe Markdown

Apprendre Git de façon interactive

Conventions et bonnes pratiques

Outils utiles

Trouver des projets open source pour contribuer

Sécurité

Lexique Git et GitHub

Terme Définition
Repository (dépôt) Espace de stockage contenant tout le code et l'historique d'un projet
Clone Copie locale complète d'un dépôt distant
Fork Copie d'un dépôt sur son propre compte GitHub
Branch (branche) Version parallèle du code permettant de travailler sans affecter la branche principale
Commit Enregistrement d'un ensemble de modifications dans l'historique
Staging (index) Zone intermédiaire où l'on prépare les fichiers avant de commiter
Push Envoi des commits locaux vers le dépôt distant
Pull Récupération et fusion des commits distants en local
Fetch Récupération des commits distants sans fusion
Merge Fusion de deux branches
Rebase Réécriture de l'historique pour intégrer des modifications d'une autre branche
Pull Request (PR) Demande d'intégration d'une branche dans une autre, avec revue de code
Issue Ticket signalant un bug, une idée ou une tâche
README Fichier de présentation principal d'un dépôt
CONTRIBUTING Fichier expliquant comment contribuer au projet
LICENSE Fichier définissant les droits d'utilisation du code
CI/CD Intégration Continue / Déploiement Continu, automatisation du cycle de développement
GitHub Actions Système d'automatisation intégré à GitHub
Workflow Fichier YAML définissant une automatisation GitHub Actions
Tag Marqueur sur un commit, souvent utilisé pour les versions (v1.0.0)
Release Publication officielle d'une version d'un projet sur GitHub
Stash Sauvegarde temporaire de modifications non commitées
Conflict Situation où deux branches ont modifié le même endroit d'un fichier
Remote Dépôt distant (par opposition au dépôt local)
Origin Nom conventionnel du remote principal (votre fork ou dépôt)
Upstream Nom conventionnel du dépôt original quand on travaille sur un fork
HEAD Pointeur indiquant le commit courant
Gitignore Fichier listant les patterns de fichiers à ne pas tracker avec Git
Semantic Versioning Convention de numérotation de version : MAJEUR.MINEUR.PATCH
Open Source Logiciel dont le code source est disponible publiquement
Maintainer Personne responsable de la maintenance d'un projet open source

FAQ Français

Q : Quelle est la différence entre git pull et git fetch ?

git fetch télécharge les nouvelles données du dépôt distant mais ne les fusionne pas dans votre branche locale. git pull fait la même chose mais fusionne automatiquement. En pratique, git fetch suivi de git rebase est souvent préféré car il donne plus de contrôle.

Q : Je me suis trompé dans mon dernier message de commit, comment le corriger ?

Si vous n'avez pas encore poussé le commit, utilisez git commit --amend -m "nouveau message". Si vous avez déjà poussé, c'est plus délicat car cela modifie l'historique. Il vaut mieux créer un nouveau commit correctif dans ce cas.

Q : Comment annuler un commit qui a déjà été poussé ?

Utilisez git revert HEAD pour créer un nouveau commit qui annule le précédent, sans modifier l'historique. C'est la méthode sûre. Evitez git reset --hard sur des commits déjà partagés avec d'autres personnes.

Q : Que faire quand j'ai un conflit lors d'un merge ?

Git marque les conflits dans les fichiers avec des indicateurs <<<<<<<, =======, >>>>>>>. Ouvrez les fichiers concernés, choisissez quelle version garder (ou combinez les deux), supprimez les marqueurs, puis faites git add et git commit pour finaliser la fusion. Visual Studio Code dispose d'un bon outil visuel pour résoudre les conflits.

Q : Faut-il commiter le dossier node_modules/ ?

Non, jamais. Le dossier node_modules/ contient les dépendances et peut peser plusieurs centaines de mégaoctets. Il doit être dans le .gitignore. Les dépendances se réinstallent avec npm install à partir du fichier package.json.

Q : Quelle est la différence entre un fork et un clone ?

Un fork est une copie d'un dépôt sur votre compte GitHub (côté serveur). Un clone est une copie locale sur votre ordinateur. Pour contribuer à un projet dont vous n'êtes pas collaborateur, vous forkez d'abord le dépôt sur GitHub, puis vous clonez votre fork localement.

Q : Quand utiliser merge vs rebase ?

merge préserve l'historique complet et est plus sûr pour les branches partagées. rebase réécrit l'historique pour le rendre plus linéaire et lisible, mais ne doit pas être utilisé sur des branches partagées avec d'autres. Pour les branches personnelles de fonctionnalité, rebase est souvent préféré. Pour les merges de PR sur main, les deux sont valides selon la convention du projet.

Q : Comment savoir quelle branche est la branche principale ?

Sur GitHub, la branche principale est indiquée dans les paramètres du dépôt et visible sur la page d'accueil. Historiquement nommée master, elle est aujourd'hui souvent renommée main. Sur votre dépôt local : git branch -a vous liste toutes les branches.

Q : Comment créer une release GitHub ?

Allez dans l'onglet "Releases" de votre dépôt, cliquez sur "Create a new release", choisissez ou créez un tag (ex : v1.0.0), ajoutez un titre et une description, puis publiez.

Q : Peut-on travailler avec Git sans ligne de commande ?

Oui. GitHub Desktop (https://desktop.github.com/) offre une interface graphique complète. Visual Studio Code intègre aussi un panneau Git. GitKraken (https://www.gitkraken.com/) est une autre option populaire.

English Version

About this guide

This guide is aimed at people who are new to programming, first-year development students, and anyone who wants to understand Git and GitHub in a practical and progressive way. No prior knowledge is required to get started.

Git is a version control tool. GitHub is an online platform that hosts Git repositories. The two are not the same thing, but they work together. This guide explains how to use them effectively, from installation to professional practices.

Visual cheat sheet (image) available in this repository :

GitHub Cheat Sheet

Downloadable PDF cheat sheet : Git-Cheat-Sheet_FR.pdf

Prerequisites

Before starting, you need :

Understanding Git and GitHub

Git is open-source software installed locally on your computer. It allows you to track the history of your files, work on multiple versions in parallel, and roll back changes if needed.

GitHub is a website that hosts your Git repositories online. It allows you to collaborate with other people, make your code public or private, and use tools like Issues, Pull Requests, and GitHub Actions.

Concept Git GitHub
Type Local software Online platform
Role Version management Hosting and collaboration
Works without internet Yes No
Free Yes Yes (with paid options)

Other alternatives to GitHub (if you are curious) :

  • GitLab : similar to GitHub, widely used in enterprise
  • Bitbucket : often used with Atlassian tools

Installation and configuration

Installing Git

Go to https://git-scm.com/downloads and download the version matching your operating system (Windows, macOS, Linux).

Verify the installation by opening a terminal and typing :

git --version

You should see something like git version 2.43.0.

Configuring your identity

Before using Git, you need to set your name and email address. This information will appear in every commit you create.

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Setting the default editor (optional)

# Use Visual Studio Code as Git editor
git config --global core.editor "code --wait"

# Use nano (simpler in terminal)
git config --global core.editor "nano"

Check your configuration

git config --list

Configure SSH authentication (recommended)

SSH authentication is more secure and convenient than using a password. It avoids entering your credentials on every operation.

# Generate an SSH key
ssh-keygen -t ed25519 -C "your@email.com"

# Display the public key to copy into GitHub
cat ~/.ssh/id_ed25519.pub

Then go to GitHub > Settings > SSH and GPG keys > New SSH key and paste your key.

Official SSH documentation : https://docs.github.com/en/authentication/connecting-to-github-with-ssh

Professional repository structure

A good repository structure makes it easier to read, maintain, and collaborate. Here is the recommended structure, used in the majority of professional projects :

my-project/
├── .github/
│   ├── workflows/            # GitHub Actions files (CI/CD)
│   │   └── ci.yml
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── PULL_REQUEST_TEMPLATE.md
├── docs/                     # Detailed documentation
│   └── architecture.md
├── src/                      # Main source code
│   ├── main/                 # Production code
│   └── test/                 # Automated tests
├── scripts/                  # Utility scripts
├── img/                      # Project images (screenshots, logos, cheat sheets...)
├── build/                    # Build files (often in .gitignore)
├── dist/                     # Distributable files (optional)
├── .gitignore                # Files to ignore in Git
├── .editorconfig             # Editor configuration
├── LICENSE                   # Project license
├── README.md                 # Main presentation file
├── CONTRIBUTING.md           # Contribution guide
├── CHANGELOG.md              # Version history
├── SECURITY.md               # Security policy
└── CODE_OF_CONDUCT.md        # Code of conduct

Role of each element

The .github/ folder

This folder is automatically recognized by GitHub. It contains configuration specific to the platform. The workflows/ subfolder contains automations (CI/CD). The ISSUE_TEMPLATE/ subfolder contains issue templates. The PULL_REQUEST_TEMPLATE.md file is the template displayed when someone opens a Pull Request.

The docs/ folder

Detailed project documentation : architecture, technical decisions, usage guides, specifications. This folder can also feed GitHub Pages to generate a static website.

The src/ folder

The application source code. It is common practice to separate main/ (production code) and test/ (tests).

The scripts/ folder

Automation, deployment, analysis, or maintenance scripts.

Root files

These files are placed at the root because GitHub recognizes and displays them automatically.

Creating structure from the GitHub web interface

This method is ideal if you are just starting out or do not yet have Git installed locally.

Step 1 : Create a new repository

  1. Go to https://github.com/new
  2. Fill in the repository name
  3. Add a short description
  4. Choose Public or Private
  5. Check "Add a README file"
  6. Choose a .gitignore file based on your language
  7. Choose a license (MIT to start with)
  8. Click "Create repository"

Step 2 : Create files and folders

To create a file in a folder that does not yet exist, click "Add file" > "Create new file" and type the path directly with /. For example, enter docs/architecture.md to create the file architecture.md in the docs/ folder.

GitHub automatically creates intermediate folders.

Step 3 : Add a CONTRIBUTING.md file

Click "Add file" > "Create new file" and name it CONTRIBUTING.md.

Step 4 : Create issue templates

Click "Add file" > "Create new file" and enter the path .github/ISSUE_TEMPLATE/bug_report.md.

Step 5 : Configure GitHub Actions

Click "Add file" > "Create new file" and enter .github/workflows/ci.yml.

Step 6 : Configure labels

In the "Issues" tab, click "Labels" to manage your labels. Recommended labels :

Label Description
bug Something is not working
enhancement New feature
documentation Documentation improvement
good first issue Great for a first contribution
help wanted External help is welcome
question Information request
wontfix This issue will not be addressed
duplicate This issue has already been reported

Creating structure from the command line

Initialize a new project

# Create the project folder and enter it
mkdir my-project
cd my-project

# Initialize the Git repository
git init

Create the complete structure in a single command

mkdir -p .github/{workflows,ISSUE_TEMPLATE} docs src/{main,test} scripts img build dist

Create the base files

touch .gitignore LICENSE README.md CONTRIBUTING.md CHANGELOG.md SECURITY.md CODE_OF_CONDUCT.md
touch .github/PULL_REQUEST_TEMPLATE.md
touch .github/ISSUE_TEMPLATE/bug_report.md
touch .github/ISSUE_TEMPLATE/feature_request.md
touch .github/workflows/ci.yml
touch docs/architecture.md

Create a comprehensive .gitignore

cat > .gitignore << 'EOF'
# Dependencies
node_modules/
vendor/
.venv/

# Build
build/
dist/
*.class
*.jar
*.war
*.ear

# Logs
*.log
*.tmp
*.swp

# Environment
.env
.env.local
.env.production

# IDE
.idea/
*.iml
.vscode/
*.suo
*.ntvs*
*.njsproj
*.sln

# OS
.DS_Store
Thumbs.db

# Tests
coverage/
.nyc_output/
EOF

Make the first commit

# Stage all files
git add .

# Create the first commit
git commit -m "feat: initial project structure"

# Connect to the GitHub repository (replace with your URL)
git remote add origin git@github.com:your-username/my-project.git

# Push to GitHub
git push -u origin main

Essential Git commands

For the complete and always up-to-date documentation : https://git-scm.com/docs

Initialize and clone

# Initialize a repository in the current folder
git init

# Clone a remote repository
git clone https://github.com/user/repo.git

# Clone into a folder with a specific name
git clone https://github.com/user/repo.git my-folder

Status and history

# View the repository status (modified files, staged, etc.)
git status

# View commit history
git log

# View history in compact form
git log --oneline

# View history with branch graph
git log --oneline --graph --all

# View differences between working directory and staging
git diff

# View differences for staged files
git diff --staged

Stage and commit

# Add a file to staging
git add filename.txt

# Add all modified files
git add .

# Create a commit
git commit -m "commit message"

# Add and commit in one command (tracked files only)
git commit -am "commit message"

# Amend the last commit message (before push only)
git commit --amend -m "new message"

Branches

# List local branches
git branch

# List all branches (local and remote)
git branch -a

# Create a new branch
git branch branch-name

# Switch to an existing branch
git checkout branch-name

# Create a branch and switch to it (recommended)
git checkout -b branch-name

# Modern way (Git 2.23+)
git switch -c branch-name

# Delete a local branch
git branch -d branch-name

# Force delete a local branch
git branch -D branch-name

Synchronize with the remote repository

# Fetch remote changes without merging
git fetch

# Fetch and merge remote changes
git pull

# Push commits to the remote repository
git push

# First push of a branch
git push -u origin branch-name

# Delete a remote branch
git push origin --delete branch-name

Merge and rebase

# Merge a branch into the current branch
git merge branch-name

# Rebase the current branch onto another
git rebase main

# Abort an in-progress merge
git merge --abort

# Abort an in-progress rebase
git rebase --abort

Stash (temporarily shelve changes)

# Stash current changes
git stash

# List stashes
git stash list

# Re-apply the latest stash
git stash pop

# Re-apply without removing the stash
git stash apply

Tags

# Create a tag on the current commit
git tag v1.0.0

# Create an annotated tag (recommended for releases)
git tag -a v1.0.0 -m "Version 1.0.0"

# List tags
git tag

# Push tags to GitHub
git push origin --tags

Roll back changes

# Unstage a file (remove from staging)
git reset HEAD filename.txt

# Discard file modifications (restore committed version)
git checkout -- filename.txt

# Undo the last commit (without deleting history)
git revert HEAD

# Reset to a specific commit hash (dangerous, rewrites history)
git reset --hard abc1234

Branches and workflow

The Git Flow model

Git Flow is a branching convention that structures teamwork. It is not mandatory, but it is a solid reference for professional projects.

Branch Role
main Stable production version
develop Ongoing development, integration
feature/name Development of a new feature
fix/name Bug fix
hotfix/name Urgent production fix
release/1.0.0 Preparing a release

Typical workflow for a feature

# Always start from an up-to-date develop branch
git checkout develop
git pull

# Create the feature branch
git checkout -b feature/my-feature

# ... work, commit ...

# Update against develop before merging
git fetch origin
git rebase origin/develop

# Open a Pull Request on GitHub from feature/my-feature to develop

Pull Requests

A Pull Request (PR) is a request to integrate your branch into another one. It is at the heart of collaborative work on GitHub. It allows the team to review the code, leave comments, and validate changes before they reach the main branch.

Best practices for a Pull Request :

  • Give a clear and descriptive title
  • Describe what the change does and why
  • Reference related issues with Closes #42 or Fixes #42
  • Keep the PR as small and focused as possible
  • Respond to review comments constructively

Commit messages

A good commit message clearly explains what was done and why. The most widespread convention is Conventional Commits : https://www.conventionalcommits.org/en/

Format

type(scope): short description

Optional body : more detailed explanation.

Optional footer : issue references, breaking changes...

Commit types

Type Usage
feat New feature
fix Bug fix
docs Documentation change
style Formatting, spaces (no logic change)
refactor Refactoring without behavior change
test Adding or modifying tests
chore Maintenance tasks, dependencies
perf Performance improvement
ci Changes related to continuous integration
build Build system changes
revert Reverting a previous commit

Examples

feat(auth): add email verification on registration

fix(api): correct HTTP status code on 404 responses

docs: update installation steps in README

chore(deps): update dependencies to latest versions

feat(user): add profile picture upload

Closes #42

GitHub Actions and CI/CD

GitHub Actions is the automation system built into GitHub. It allows you to trigger automatic actions on events (push, pull request, deployment, etc.).

Official documentation : https://docs.github.com/en/actions

Basic CI workflow example

This file must be placed in .github/workflows/ci.yml :

name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

      - name: Check code style
        run: npm run lint

Example for a PHP/Symfony project

name: CI PHP

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Install Composer dependencies
        run: composer install

      - name: Run PHPStan
        run: vendor/bin/phpstan analyse

      - name: Run PHPUnit tests
        run: vendor/bin/phpunit

Main triggers

Trigger Description
push On every push to a branch
pull_request When a PR is opened or updated
schedule On a cron schedule
workflow_dispatch Manual trigger
release When a release is created

Contributing to open source

Open source is at the heart of the development ecosystem. Contributing to an existing project is an excellent way to learn, build visibility, and give back to the community.

GitHub official guide on contributions : https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project

Steps to contribute

1. Find a project

2. Fork the repository

The fork creates a copy of the repository on your GitHub account. Click the "Fork" button at the top right of the project page.

3. Clone your fork

git clone git@github.com:your-username/the-project.git
cd the-project

4. Add the original repository as a remote

git remote add upstream git@github.com:original-author/the-project.git

5. Create a branch for your contribution

git checkout -b feature/my-contribution

6. Make your changes and commit

git add .
git commit -m "feat: add my contribution"

7. Update your fork with the latest changes from the original

git fetch upstream
git rebase upstream/main

8. Push and open a Pull Request

git push origin feature/my-contribution

Then go to GitHub and open a Pull Request from your branch to the original project's main branch.

9. Respond to feedback

The project maintainer will review your code and may request changes. Stay open to feedback, it is normal and constructive.

Points to keep in mind

  • Always read the CONTRIBUTING.md file before starting
  • Check that there is not already an issue or PR for what you want to do
  • Respect the project's code style
  • Write tests if the project has them
  • Be patient : maintainers are often volunteers

Important repository files

File Role Required
README.md Project presentation Strongly recommended
LICENSE Usage license Yes for open source
CONTRIBUTING.md Contribution guide Recommended
CHANGELOG.md Version history Recommended
SECURITY.md How to report a vulnerability Recommended
CODE_OF_CONDUCT.md Rules of behavior Recommended
.gitignore Files ignored by Git Yes
.editorconfig Editor config for everyone Optional

Most common licenses

License Usage Link
MIT Very permissive, free use opensource.org/licenses/MIT
Apache 2.0 Permissive, patent mention apache.org/licenses/LICENSE-2.0
GPL v3 Copyleft, derived code must stay free gnu.org/licenses/gpl-3.0
AGPL v3 Like GPL but also for web services gnu.org/licenses/agpl-3.0
LGPL Permissive for libraries gnu.org/licenses/lgpl-3.0
ISC Similar to MIT, very short opensource.org/licenses/ISC

Tool to choose a license : https://choosealicense.com/

GitHub Badges

Badges are small images displayed in the README. They communicate important information at a glance : build status, version, license, test coverage...

Badge generator : https://shields.io/

Common badges

# CI status
[![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions)

# License
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# Version
[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/user/repo/releases)

# Test coverage
[![Coverage](https://img.shields.io/codecov/c/github/user/repo)](https://codecov.io/gh/user/repo)

# PRs welcome
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

# GitHub stars
[![GitHub stars](https://img.shields.io/github/stars/user/repo?style=social)](https://github.com/user/repo/stargazers)

# Latest release
[![GitHub release](https://img.shields.io/github/v/release/user/repo)](https://github.com/user/repo/releases)

# Last commit
[![GitHub last commit](https://img.shields.io/github/last-commit/user/repo)](https://github.com/user/repo/commits/main)

Resources and links

Official documentation

Markdown syntax

Learn Git interactively

Conventions and best practices

Useful tools

Find open source projects to contribute to

Security

Git and GitHub Glossary

Term Definition
Repository Storage space containing all the code and history of a project
Clone Full local copy of a remote repository
Fork Copy of a repository on your own GitHub account
Branch Parallel version of the code allowing work without affecting the main branch
Commit Record of a set of changes in history
Staging (index) Intermediate area where files are prepared before committing
Push Sending local commits to the remote repository
Pull Fetching and merging remote commits locally
Fetch Fetching remote commits without merging
Merge Merging two branches
Rebase Rewriting history to integrate changes from another branch
Pull Request (PR) Request to integrate a branch into another, with code review
Issue Ticket reporting a bug, idea, or task
README Main presentation file of a repository
CONTRIBUTING File explaining how to contribute to the project
LICENSE File defining the rights to use the code
CI/CD Continuous Integration / Continuous Deployment
GitHub Actions Automation system built into GitHub
Workflow YAML file defining a GitHub Actions automation
Tag Marker on a commit, often used for versions (v1.0.0)
Release Official publication of a project version on GitHub
Stash Temporary save of uncommitted changes
Conflict Situation where two branches modified the same place in a file
Remote Remote repository (as opposed to local repository)
Origin Conventional name for the main remote (your fork or repository)
Upstream Conventional name for the original repository when working on a fork
HEAD Pointer indicating the current commit
Gitignore File listing file patterns not to track with Git
Semantic Versioning Version numbering convention : MAJOR.MINOR.PATCH
Open Source Software whose source code is publicly available
Maintainer Person responsible for maintaining an open source project

FAQ English

Q : What is the difference between git pull and git fetch ?

git fetch downloads new data from the remote repository but does not merge it into your local branch. git pull does the same but merges automatically. In practice, git fetch followed by git rebase is often preferred because it gives more control.

Q : I made a mistake in my last commit message, how do I fix it ?

If you have not pushed the commit yet, use git commit --amend -m "new message". If you have already pushed, it is trickier because it rewrites history. It is better to create a new corrective commit in that case.

Q : How do I undo a commit that has already been pushed ?

Use git revert HEAD to create a new commit that undoes the previous one, without modifying history. This is the safe method. Avoid git reset --hard on commits already shared with others.

Q : What to do when I have a conflict during a merge ?

Git marks conflicts in files with indicators <<<<<<<, =======, >>>>>>>. Open the affected files, choose which version to keep (or combine both), remove the markers, then do git add and git commit to finalize the merge. Visual Studio Code has a good visual tool for resolving conflicts.

Q : Should I commit the node_modules/ folder ?

No, never. The node_modules/ folder contains dependencies and can weigh several hundred megabytes. It must be in .gitignore. Dependencies are reinstalled with npm install from the package.json file.

Q : What is the difference between a fork and a clone ?

A fork is a copy of a repository on your GitHub account (server side). A clone is a local copy on your computer. To contribute to a project you are not a collaborator on, you first fork the repository on GitHub, then clone your fork locally.

Q : When to use merge vs rebase ?

merge preserves the full history and is safer for shared branches. rebase rewrites history to make it more linear and readable, but should not be used on branches shared with others. For personal feature branches, rebase is often preferred. For merging PRs into main, both are valid depending on the project convention.

Q : How do I know which branch is the main branch ?

On GitHub, the main branch is indicated in the repository settings and visible on the home page. Historically named master, it is often renamed main today. On your local repository : git branch -a lists all branches.

Q : How do I create a GitHub release ?

Go to the "Releases" tab of your repository, click "Create a new release", choose or create a tag (e.g., v1.0.0), add a title and description, then publish.

Q : Can I work with Git without the command line ?

Yes. GitHub Desktop (https://desktop.github.com/) offers a full graphical interface. Visual Studio Code also integrates a Git panel. GitKraken (https://www.gitkraken.com/) is another popular option.

Author

Fabien Conéjéro - https://github.com/madjeek-web

License

This project is licensed under the MIT License. See the LICENSE file for details.

GitHub Projects - FAQ

Q : What is this ? How does it work, explain simply ?

What is GitHub Projects ?

It is a task management tool integrated into GitHub. Imagine a table like Notion or Trello, but directly linked to your code.

What is it concretely used for ?

When you work on a project (alone or in a team), you have a lot of things to manage : bugs to fix, features to add, things in progress... GitHub Projects allows you to follow all of this visually without leaving GitHub.

How does it work ?

You create "issues" (= tasks, like "fix the login bug" or "add the dark mode button"), and you organize them in a table. You can filter them (ex : see only bugs), sort them (by priority, by date...), group them (by status : To do / In progress / Done), and add custom fields (priority, deadline, responsible...).

What you see on your screen

You have a project with 1 open issue and 0 closed. It is in Private mode (no one else can see it).

In summary : it is like a professional to-do list for your code. Very useful when your project grows and you do not want to lose track.

Q : Is it private or public ?

Based on what is displayed : Private.

We can clearly see "Private" next to the project name. So only you can see it.

Q : On the web, in public mode, can it also be public ?

Yes exactly ! A GitHub project can be :

  • Private : only you (or your team) can see it
  • Public : anyone on the internet can view it

"There aren't any projects yet" means this person has no public projects visible on their profile. Either they have not created any, or they are all set to private.

In summary : when you create a project, you choose yourself whether it is public or private.

Q : What is the point of showing things there in public mode ?

To show your seriousness when you are looking for a job or an internship. A recruiter who visits your GitHub can see not only your code, but also how you organize yourself, how you manage your tasks... it looks professional.

For open source projects, if other developers contribute to your code, they can see what remains to be done, what is in progress, and organize themselves with you without having to ask you every time.

For transparency, if you develop a tool used by people, they can follow the progress, see known bugs, know what you plan to add...

In short, in private mode it is your personal draft, in public mode it is your professional showcase.

Q : Same questions for : Overview, Repositories, Projects, Packages, Stars.

These are the tabs of your GitHub profile, here is what each one is used for.

Overview

This is your main page, what people see first. You can put a presentation of yourself, your stats (commits, contributions...). It is your business card.

Repositories

This is where all your code projects are stored. Each "repo" = one project (a website, an app, a script...). Public or private, this is where your code lives.

Projects

We just talked about it ! These are your task management tables. Linked to your repos to organize your work.

Packages

This is more advanced. It allows you to publish libraries or tools that other developers can install and reuse in their own projects. At your level you will probably not use it right away.

Stars

When you find a nice project on GitHub, you can give it a star (like a "like"). This tab shows all the projects you have liked, handy for finding them later.

In summary : Repositories = your code, Projects = your organization, Stars = your favorites, Packages = what you share with the community.

༄☕︎︎︎ Buy Me A Coffee :

Buy Me A Coffee image

༄☕︎︎︎ stripe.com

. Thank you for your support

About

Features and craftsmanship with GitHub - Guide / Helper - Git Cheat Sheet

github.com/madjeek-web

Topics

github git teachers students documentation helper cheatsheet starter-kit beginner welcome beginner-friendly beginners base-project guidebook junior-developer github-actions github-config github-guide madjeek fabien-conejero

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors