Bitbucket GIT: gérer les versions des fichiers sources du projet

Présentation de Bitbucket et GIT

Inspiré de la présentation de GIT par le CNRS.

Bitbucket est un site en ligne bâti autour de l’outil de gestion du code « GIT » (se prononce « guite »). L’objectif de ce type d’outils est de faciliter l’échange, le travail collaboratif et la gestion des conflits (en particulier lorsque plusieurs personnes travaillent en même temps sur le même document). Cela permet également de simplifier le déploiement des versions du site sur le serveur d’hébergement (un serveur OVH par exemple).

Notion de dépôt (synonyme en anglais: repository): un dépôt GIT est un répertoire nommé « .git » (répertoire caché) situé à la racine du projet et qui contient l’historique du projet: la liste des fichiers du projet, et tous les changements qui ont été réalisés sur ces fichiers: ajout, suppression ou modification d’un fichier PHP par exemple. Sauf rarissimes exceptions, il ne faudra jamais modifier son contenu directement, mais uniquement en passant par les commandes GIT.

Notion de commit: L’historique d’un projet est une séquence de « photos », contenant l’état de tous les fichiers du projet. Ces « photos » s’appellent des commits, et possèdent:

  • une date
  • un auteur
  • une description textuelle
  • un lien vers le(s) commit(s) précédent(s) (On parle également de révision).

GIT est dit « décentralisé », car il y a un dépôt « central » (ou dépôt distant), qui est hébergé sur le site Bitbucket, mais chaque personne de l’équipe travaille sur son propre dépôt GIT. Le principe est le suivant:

  1. je récupère sur mon ordinateur la dernière version du dépôt GIT centralisé sur le projet Keleril sur le site Bitbucket (commande git clone [url du dépôt distant]), je dispose alors d’un dépôt GIT local
  2. je modifie le projet sur mon dépôt local: création de nouveaux fichiers, modification de fichiers existants…
  3. une fois le travail terminé, j’ajoute les nouveaux fichiers dans mon dépôt local (commande git add [mon fichier]), je commit les modifications (commande « git commit [mes fichiers ajoutés/modifiés] »)
  4. pour mettre à jour le dépôt distant, je pousse les modifications de mon dépôt local vers le dépôt distant (commande git push)

Préparation du poste local

Installation du logiciel GIT sur le poste PC (sous Windows)

Dans un premier temps, il faut installer sur son PC le logiciel GIT For Windows: https://gitforwindows.org. Plusieurs outils sont installés pour utiliser git soit en tapant des lignes de commandes (par exemple git commit -m "Commentaire sur mon commit"), soit pour agir directement dans le dossier du dépôt GIT à l’aide du menu contextuel (clic-droit sur le dossier ou sur un fichier).

Sur Mac OS X, git peut être déjà installé (tester la commande git depuis un terminal), sinon la manière la plus simple de l’installer consiste à installer Xcode Command Line Tools.

Génération et partage des clés de chiffrement privée / publique entre le dépôt local (sur le PC) et le dépôt distant (sur bitbucket.com)

La création et le partage de clés de chiffrements est une étape un peu compliquée mais nécessaire pour faire communiquer le dépôt local (sur le PC) avec le dépôt distant sur Bitbucket. Pour des raisons de sécurité, les échanges entre les dépôts sont chiffrés et autorisés uniquement à partir de machines qui partagent des clés secrètes avec le dépôt sur Bitbucket. La procédure nécessite dans un premier temps de générer depuis son PC (ou son Mac le cas échéant) une paire de clés cryptographiques ou clés de chiffrement:

  1. Une clé privée qui est enregistrée dans un répertoire caché appelé « .ssh » dans le dossier « racine » de GIT sur le PC
  2. Une clé publique qui sera enregistrée sur le dépôt Keleril sur Bitbucket

Détail de la procédure:

  • Lancer le programme GIT Bash installé lors de l’étape précédente (ce programme permet de lancer des lignes de commandes – git en particulier, mais pas seulement – dans une émulation de machine linux)
  • Sur l’invite de commande affichée, taper la commande suivante (en remplaçant l’adresse e-mail par ma propre adresse):
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
  • Après génération de la clé aléatoire, l’interface demande le nom du fichier de sauvegarde de la clé (privée). Ne rien saisir, cliquer simplement sur la touche ‘Entrée’ pour accepter le nom par défaut affiché entre parenthèses

Enter file in which to save the key (/c/Users/jbh/.ssh/id_rsa):

  • Saisir un mot de passe (qu’il faudra saisir à chaque transfert entre le dépôt local et distant, donc pas trop simple mais pas trop long non plus)
  • Aller sur le dossier « /c/Users/[nom du compte windows]/.ssh » depuis l’explorateur de fichiers, 2 fichiers on été créés:
  1. id_rsa: contient la clé privée
  2. id_rsa.pub: contient la clé publique
  • il faut récupérer le contenu de la clé publique à l’aide d’un éditeur de texte (notepad, pour notepadd++ qui est gratuit sur Windows). Exemple de clé publique:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDB92GIc+R75HEm1y0kNdLQXuFPQi+3Op20vJawUi4qsCxR0dF2LMNOS0v4R/oXua6J7Av3NBC0YkpGw993E37fvB6FEorDP2PZLicaPOmZlsvCymgX/mnKXGH7cOPJabYMI53sS/kuwcH5PwJa5cn9gTPoEY2iOR0Ui7useLzut40kwHHxTGA9lLoeZERG814NwOjKKEbMJWL2Eij81HtF0Qoa1ERCTseLNeDmbCKd+3f42DweKEXnw4pR+SH+F2eVs3dKw4liyg5kNw43M6fUdFIQjzTVDcaAzQpfIblSsh12ECYDj8TzcNdNOunUinNuRVegrf9FSWAQVTB9HF3dQmzIVDD0ueDNj/adnDdYrIrUdmG5K09nJJ7ydERCUDMDDx6UM5Uv2gLvAdfzjIFTJpWuYVSktPlSlgckwFIXYpww1uSfiTks4Wlq7h+viBtlw9rifMQ9W0y+P/3JO1/Zv3URmo+QWoIsrO4FWvItNBjCkk3o3qiLHbBnmlhY6jZg9j7PIE01lNpEvtyva4rNn03mrCgR+K4OQ1fCbCQtg+KcDr9SEFPDzwnnVVpmJxuFzRDzGRI3b38+d02sdOxpAl/TKPvXhZnSVCs+dVd3RTBnStYS8RBt1Utiu7ZPlzIkUOqtFYlg2JOJylZ2DikPH+F4bp7SruRCW0o91xng+Q== your_email@example.com

  • se connecter sur le site Bitbucket et aller sur l’URL: https://bitbucket.org/kelerilteam/warinkeleril
  • cliquer sur la roue crantée (settings), puis sur le menu « Access key »
  • cliquer sur le bouton « Add key »
  • Donner un nom à la clé publique (par exemple « Clé PC Keleril ») et coller la clé dans le champ « key », cliquer sur le bouton « Add key »

Pour terminer l’installation de GIT sur le PC, il faut fournir un e-mail et un nom par défaut à l’aide des commandes suivantes dans GIT Bash:

git config --global user.email "your_email@example.com"

Puis:

git config --global user.name "My firstname and name"

Compléments de l’installation de GIT

C’est optionnel, mais rapidement nécessaire: créer un fichier « .gitignore » à la racine du projet. Ce fichier permet de lister les éléments (dossiers, fichiers) qui ne doivent pas être pris en compte par GIT (et donc jamais ajoutés dans les dépôts). Référence: https://git-scm.com/docs/gitignore.

Deux exemples:

  • on voudra écarter des fichiers de configuration qui contiennent des mots de passes (bases de données…) comme dans le cas de Keleril le fichier config.inc.php: On pourra proposer un fichier config.inc.example.php indexé lui dans le dépôt GIT pour que les utilisateurs du projet disposent d’un modèle pour paramétrer leurs propres accès en fonction de leur environnement de développement.Le fichier config.inc.php doit être créé par chaque utilisateur (et également sur le serveur de production), mais il doit être écarté de l’indexation GIT, pour éviter qu’il ne soit proposé à l’ajout lors de chaque commit.

A ce sujet il existe une solution assez simple proposée en PHP pour gérer les configuration: voir Dotenv PHP.

  • Si le projet utilise des librairies PHP externes au projet, en bonne pratique il vaut mieux utiliser des gestionnaires de dépendances PHP – comme par exemple PHP Composer – qui après chaque installation du dépôt vont charger les librairies externes dans un dossier dédié (dossier vendor dans le cas de Composer). Le dossier en question doit être écarté de l’indexation GIT car les librairies ne font pas directement partie du projet (et la gestions des mises à jours de librairies serait alourdie).

Opérations courantes sur le dépôt GIT

Clonage du dépôt distant (sur bitbucket.com) sur le poste PC

Pour créer le dépôt local sur lequel travailler, il suffit de cloner le dépôt distant (commandes git clone [url du dépôt distant]).

  1. créer un dossier dédié sur le PC (par exemple je crée en général un dossier nommé undergit, qui contiendra uniquement des dépôts GIT (chemin complet sur mon PC: « C:\Users\jbh\Documents\JBHR\dev\workspace\undergit »).
  2. dans ce dossier, faire un clic-droit, et lancer l’application GIT Bash (GIT Bash fonctionne avec des lignes de commandes, il y a aussi GIT GUI qui fonctionne avec une interface graphique mais c’est une question de goût ).
  3. utiliser la commande suivante (que l’on peut retrouver facilement grâce au bouton « Clone » sur le site Bitbucket sur l’écran « https://bitbucket.org/kelerilteam/warinkeleril/src/master/ » , à copier-coller sur GIT Bash à l’aide du clic-droit):
git clone git@bitbucket.org:kelerilteam/keleril.git

Le répertoire « keleril » est créé dans le dossier undergit, avec un dossier « .git » dedans: il s’agit du dépôt local.

Récupérer la version à jour du dépôt distant

Si le dépôt distant a été modifié par une autre personne travaillant sur le même projet, il faut faire une opération appelée checkout afin de récupérer la dernière version du dépôt distant sur son dépôt local:

  1. faire un clic-droit dans l’explorateur sur le dossier « keleril ». Ouvrir l’application GIT Gui Here (pour ne pas avoir à saisir des lignes de commandes).
  2. Depuis le menu déroulant « Branch », sélectionner Checkout… (ou faire directement un ctrl-O au clavier)
  3. Conserver les options par défaut (option « Local branch » et valeur « master » dans la liste, case à cocher: Fetch Tracking Branch), cliquer sur le bouton « Checkout ».

Si des commits ont été poussés sur le dépôt distant et pas sur le dépôt local, ce dernier sera mis à jour.

Exemple 1: ajouter un nouveau fichier dans le dépôt local puis le pousser sur le dépôt distant

Commandes utilisées sur mon PC pour ajouter ce fichier de présentation au format markdown: « README.MD »

  1. Créer le fichier README.md dans le répertoire « keleril » (à l’aide d’un éditeur de texte comme Notepad, Notepad++ ou un logiciel de développement – IDE – comme Netbean ou PHPStorm) et éditer le fichier.
  2. Une fois l’édition terminée, faire un clic-droit dans l’explorateur sur le dossier « keleril ». Ouvrir l’application GIT Gui Here (pour ne pas avoir à saisir des lignes de commandes).
  3. Le nouveau fichier README.md est affiché dans la rubrique « Unstaged changes » car il n’est pas encore indexé dans la dépôt GIT. Il suffit de cliquer sur l’icône du fichier à gauche du nom README.md pour le faire basculer sur la rubrique « Staged changes (will commit) ».
  4. Saisir le commentaire: « Ajout du fichier de présentation du projet War in Keleril » dans le champ « Commit Message ».
  5. Cliquer sur le bouton Commit

Le message « Created commit [identifiant du commit] » doit être affiché en bas de l’écran de GIT GUI Le fichier README.md est désormais indexé et commité sur le dépôt local. Il reste à le « pousser » sur le dépôt distant:

  1. Toujours sur GIT GUI, cliquer sur le bouton Push
  2. Conserver les valeurs par défaut proposées (Source Branches=origin, Remote=master) et cliquer encore sur le bouton Push
  3. Le mot de passe de la clé de chiffrement privée est demandé, le saisir

Le transfert (push) doit se réaliser correctemment avec le message: « 9d298c9..cb791c1 master -> master »

GIT GUI (GIT For Windows)
Capture d’écran de GIT GUI (GIT For Windows)

Exemple 2: modifier un fichier existant dans le dépôt local puis le pousser sur le dépôt distant

Commande utilisées sur mon PC pour modifier ce fichier de présentation au format markdown: « README.MD »

  1. Modifier le fichier README.md dans le répertoire « keleril » (à l’aide d’un éditeur…)
  2. Une fois l’édition terminée, faire un clic-droit dans l’explorateur sur le dossier « keleril ». Ouvrir l’application GIT Gui Here (pour ne pas avoir à saisir des lignes de commandes).
  3. Le nouveau fichier README.md est affiché dans la rubrique « Unstaged changes ». Cliquer sur l’icône du fichier à gauche du nom README.md pour le faire basculer sur la rubrique « Staged changes (will commit) » (ou bien cliquer sur le bouton « Stage changed » qui basculera l’ensemble des fichiers modifiés).
  4. Saisir le commentaire: « Ajout exemple modification fichier dans le README.md » dans le champ « Commit Message ».
  5. Cliquer sur le bouton Commit

Le message « Created commit [identifiant du commit] » doit être affiché en bas de l’écran de GIT GUI Le fichier README.md est désormais indexé et commité sur le dépôt local. Il reste à le « pousser » sur le dépôt distant:

  1. Toujours sur GIT GUI, cliquer sur le bouton Push
  2. Conserver les valeurs par défaut proposées (Source Branches=origin, Remote=master) et cliquer encore sur le bouton Push
  3. Le mot de passe de la clé de chiffrement privée est demandé, le saisir

Le transfert (push) doit se réaliser correctemment avec le message:

9d298c9..cb791c1 master -> master

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *