Tuto d'utilisation de Git

[Thierry]

Tuto Partie 1 : Démarrer sous Windows

Git est un logiciel de gestion de versions, gérant à la fois l'historique de ses fichiers, et l'accès à des utilisateurs dotés de droits : lecture, création, modification, etc... Créé par Linus Torvalds, le créateur de Linux, c'est un produit libre, c'est à dire utilisable et modifiable par tout le monde, en respectant sa licence de distribution, bien sûr.

De nombreux sites proposent d'héberger vos codes source à travers un Git local. Les plus connus sont SourceForge et GitHub, mais il y en a de plus petits comme Gitlab, Gitorious ou Framasoft, fournisseurs de produits libres Français depuis des années. Locoduino a choisi Framasoft et installé ses quartiers de code dans Framagit. Vous pouvez y retrouver tous ses sources ici (https://git.framasoft.org/groups/locoduino.org).

Le site Framagit est organisé autour des utilisateurs, qui peuvent se regrouper sous un même nom, comme Locoduino.org. Chaque utilisateur, ou chaque groupe, dispose d'une liste de projets. Chaque projet est un 'coffre' ou un 'dépot' Git.

La première chose à faire est donc de s'inscrire sur Framagit.

Ensuite, il convient de créer votre premier projet en lui donnant un nom et une visibilité (privé, public...). Ce projet sera le réceptacle de votre travail. Le site propose tout de suite de créer un fichier README.md, faisons le pour disposer juste d'un point de départ... Cliquons sur le lien proposant la création, entrons un peu de texte sur le projet à venir, et sauvons en cliquant sur le bouton 'Commit changes'. Vous noterez que ce bouton refusera de fonctionner si aucun texte de Commit (Commit message) n'est rempli ! C'est le fonctionnement normal de Git qui veut absolument garder une trace de chaque opération effectuée sur le projet.
Voilà, vous avez un dépôt Git avec un peu de contenu !
Pour pouvoir autorisez une machine quelconque à accéder à ce dépôt, il va falloir l'authentifier auprès de Git. Pour cela nous avons besoins d'outils sous Windows.
Malgré mon âge avancé et mon expertise dans ce domaine, je ne suis pas partisan de l'utilisation de la ligne de commande. C'est pourquoi je privilégie toujours lorsque c'est possible l'utilisation d'outils modernes et interactifs.
Depuis le début (récent) de mon utilisation de Git, j'ai installé 'Git Extensions' qui est disponible depuis... SourceForge ! (https://sourceforge.net/projects/gitextensions/). Cet outil graphique d'accès à un dépôt Git permet d'éviter 99% des besoins de la ligne de commande très chères aux Linuxiens.
Outre Git Extensions lui même, l'installeur met en place de petits outils annexes comme PuTTY qui va nous servir à nous faire reconnaître.
Pour que Git authentifie une machine, il nous faut créer une clé SSH et envoyer le partie publique à Framagit, et conserver la partie privée sur notre machine.
Dans Git extensions, utiliser la commande 'Outils/PuTTY/Générer ou importer une clé' .



Suivre les instructions et lorsque la clé est générée, sauver les clés publiques et privées à un endroit sécurisé mais accessible (vous en aurez besoin à chaque connexion à Git...) et dans des fichiers différents. Attention, pour créer la clé privée, vous devrez donner une phrase clé, qui vous sera demandée à chaque connexion. C'est comme un mot de passe, il faut impérativement bien la retenir, y compris les majuscules/minuscules... La vidéo associée à Git extensions dans SourceForge explique bien tout cela, si on comprend l'Anglais supersonique de la narratrice vraisemblablement Indienne.

Laissez PuTTY ouvert, et retournons dans Framagit. Lorsque vous êtes sur le projet, allez dans les settings de votre profil. A gauche vous devez avoir une option 'SSH Keys' avec probablement '0' à côté. Copiez collez le texte de PuTTY de clé publique (le long texte imbuvable de plusieurs lignes, et plus grand que la taille visible, allez jusqu'au bout !) dans le cadre nommé 'Key'. Donnez un nom à votre clé dans 'Title' et cliquez sur Add Key. Voilà, cette clé vous identifiera pour Git.

Du côté Windows, dans Git Extensions, cliquez sur 'Outils/PuTTY/Démarrer l'agent d'authentification'. Cette commande va lancer une petite application qui va se coller dans les icônes de la barre de tâches. Cliquez droit dessus et utilisez 'Add key' qui va vous demander le fichier de clé privée, ainsi que la phrase clé. Une fois tout ça entré, la partie privée de la clé qui vous identifie est disponible a qui la demande. Vous êtes prêts pour la suite !

Je continuerais demain (si tout va bien) pour les manipulations de Git.

[Thierry]

Tuto Partie 2 : le clonage

Pour pouvoir travailler à remplir et modifier le contenu du dépôt Git, il va falloir en avoir un exemplaire sur votre machine. Cela s'appelle le clonage. Le principe est de reproduire l'arborescence des fichiers du projet quelque part sur votre machine. Ce nouveau répertoire sera une copie conforme, et Git ira y trouver vos changements à envoyer (commiter) ensuite vers le dépôt distant sur Framagit.

Lancer Git extensions, et utiliser le lien 'Cloner un dépôt' en haut à gauche. Une fenêtre va s'ouvrir pour demander plusieurs choses.



La première est le dépôt à copier : l'adresse se trouve sur la page du projet dans Framagit et commence par git@git.framasoft.org: .
La deuxième est le répertoire devant accueillir le répertoire du projet. Typiquement, dans nos usages, si c'est un projet Arduino, la réponse se termine par 'Mes documents/Arduino'. Si c'est un projet, alors c'est plutôt 'Mes documents/Arduino/Libraries' .
La troisième est le nom du répertoire de votre projet.
La dernière concerne la notion de branches que nous n'aborderons pas tout de suite. Laissons la vide.

Laisser le reste dans l'état, et cliquer sur le bouton 'Cloner'. Si PuTTY est bien lancé et votre clé enregistrée, alors l'arborescence est créée sur votre machine !

[DDEFF]

Bloqué au code SSH à rentrer :

Message :

À cause de la migration de notre gitlab vers un autre serveur, l'empreinte SSH du serveur a changé. Ne vous en inquiétez pas. Faites un ssh-keygen -f ~/.ssh/known_hosts -R git.framasoft.org et cela refonctionnera.

Voilà voilà....

[Thierry]

Tu n'as pas besoin de faire ça si tu n'as jamais utilisé PuTTY. Si tu l'avais déjà installé, alors il faudrait aller voir dans les registres avec regedit, clé 'HKEY_CURRENT_USER\SOFTWARE\SimonTatham\PuTTY\SshHostKeys' et enlever la valeur framasoft.org si elle est là.
Ce message s'affiche tout le temps depuis qu'ils ont fait la fameuse migration, mais tu n'as pas forcément besoin de faire cette manip !

[Thierry]

Tuto Partie 3 : Au quotidien

Vous disposez maintenant d'un dépôt de vos sources chez un hébergeur de confiance, d'un dépôt local représentant une copie de ce dépôt distant pour travailler confortablement, et d'un accès privilégié à ce dépôt distant grâce à une clé cryptée réputée inviolable (ou très difficilement) !

Vous pouvez maintenant travailler tranquillement dans votre dépôt local, créer, modifier, supprimer des fichiers et des répertoires exactement comme avant, sans vous préoccuper de rien. Mais au bout d'un moment vous allez vouloir sauver vos fichiers dans votre dépôt local, voire envoyer le fruit de votre dur labeur vers votre dépôt distant, pour le sauver, mais aussi peut être pour le partager...
Votre dépôt local n'est pas qu'un simple répertoire, c'est aussi un historique de vos modifications qui est conservé, et auquel vous pouvez revenir à n'importe quel moment... Envoyer vos fichiers vers ce dépôt local correspond donc à l'enregistrement de l'état de ces fichiers et répertoires à l'instant 't', sous un nom bien précis. A tout moment, vous pourrez annuler une modification et revenir à un état antérieur, comparer votre source actuel à ce qu'il a été à une date ou une version précise... Bref, c'est beaucoup plus qu'une simple sauvegarde de vos sources ! Voyons comment procéder.

Lancez Git Extensions et ouvrez votre dépôt. Dans la barre d'icônes en haut, vous en avez une qui attire l'oeil, 'Commiter', suivi d'un nombre.



C'est le nombre de modifications que Git a détecté dans l'ensemble de ce dépôt. Cette recherche est automatique, et concerne absoument tous les fichiers présents dans le répertoire du dépôt, pas seulement les sources. En cliquant sur cette icône, Git extensions ouvre une nouvelle fenêtre qui va vous permettre de mieux comprendre ces modifications.



En haut à gauche, tous les fichiers détectés différents, avec le type de modification comme icône (ajout, suppression, modification...). Si vous sélectionnez un fichier, vous verrez à droite un récapitulatif des modifications apportées, avec sur fond rouge les anciennes lignes, et sur fond vert les nouvelles. Dans le cas d'un ajout ou d'une supression, c'est le contenu du fichier qui est affiché. Avant de passer à la suite, il peut être nécessaire de limiter la recherche de ces modifications sur des fichiers que vous ne pousserez jamais dans le dépôt, comme des résultats de compilation, des fichiers temporaires, ou des fichiers personnels. C'est le rôle d'un petit fichier texte apparu à la racine de votre dépôt et qui s'appelle '.gitignore'. Il recense les fichiers et répertoires que vous n'avez pas envie de voir apparaître ici, dans la liste des fichiers modifiés. Si l'un de ceux que vous voyez est dans ce cas, vous avez deux solutions. Soit éditer manuellement '.gitignore' et y ajouter le nom incriminé (répertoire, nom générique comme *.txt, ou nom précis), soit utiliser la commande du menu contextuel du fichier 'Ajouter le fichier à .gitignore'.
Une fois le ménage fait dans les fichiers modifiés, il faut dire à Git lesquels représentent bien ce qui doit être mis au dépôt. Git dit 'indéxer un fichier'. Désindexer est bien sûr l'opération inverse. Les quatre petites flèches violettes de gauche permet de construire la liste du bas, qui représente ce que vous voulez commiter, c'est à dire envoyer au dépôt. Il n'est pas toujours souhaitable de tout commiter. Par exemple si vous voulez mettre une petite correction à disposition alors que vous avez touché à autre chose...
Une fois le choix fait, vous pouvez commiter, c'est à dire enregistrer ces modifications comme étant l'état de votre dépôt local.
Pour l'instant, vous avez travaillé localement... Si vous êtes sûr de vos modifications, alors vous pouvez peut être les 'pousser', c'est à dire les envoyer -aussi- vers le dépôt distant. En effet, votre dépôt distant ne peux pas prendre des modifications différentes de celles que vous avez commité localement. Sinon il en résulterait un décalage qui ne peux pas fonctionner. Pas contre vous pouvez commiter plusieurs fois localement, avant de tout pousser d'un seul coup chez Framasoft !
Bref, dans cette fenêtre, vous 'commitez', ou vous 'commitez' et 'poussez' en même temps ! Pour que la manip puisse avoir lieu, n'oubliez pas de donner un message de commit, c'est obligatoire. Enfin les autres boutons vous proposent de réinitialiser les fichiers de la liste des indexés pour les ramener dans l'état précédent. Attention, vous perdrez vos modifications !

[DDEFF]

Merci Thierry,
Je ne pensais pas faire cette manip et, pour info, en faisant regedit, je ne trouve pas .... \SimonTaham\... et, donc, pas de clé à enlever.

Non. Là où ça bloque, c'est pour recopier la clé publique.

Je l'avais sauvée sous Word et ça ajoute plein de choses (dont des fins de ligne) et je comprends que ça foire.
Là je l'ai sauvée sans extension pour ne pas la dénaturer.
Et si je l'ouvre avec le block-note, il me dit "clé invalide".
J'ai essayé en mettant tout (y compris les commentaires et titre), sans les commentaires et titres, en supprimant les sauts de ligne (il se plaignait qu'il fallait une seule ligne), et ... j'en suis toujours là.
Satanée clé 

[Thierry]

Tout n'est pas perdu ! Je viens de le faire, il faut juste vraiment faire un copier coller du texte de la fenêtre du haut (regardes le premier post, j'ai ajouté une image...) en prenant bien tout, la clé est plus longue que ce que l'on voit. Si tu as déjà refermé PuTTY, pas de panique ! Tu ouvres à nouveau l'outil de génération de clé, tu utilises l'option 'File/Load Private Key' en donnant ton fichier de sauvegarde, et après l'entrée de la fameuse phrase clé, tu as à nouveau le cadre de la clé publique rempli ! Au pire, tu peux recréer une nouvelle clé, on est pas limité ! Quand je parle de sauvegarde, je parle du fichier créé avec l'option 'Save public key' et rien d'autre ! Utiliser Word n'est pas une option !

[DDEFF]

Alléluia !!
Je continue.

[DDEFF]

J'ai avancé, je suis arrivé là.


Quand j'ai appuyé sur commit la première fois, dans la fenêtre, tous les fichiers étaient déjà dans la case en bas à gauche.
J'ai utilisé "commiter et pousser", tout s'est apparemment bien passé, sauf que j'ai seulement le README.md sur framasoft.
Et maintenant, je n'ai plus aucun fichier dans la fenêtre de commit...

[Thierry]

Regardes un peu mieux sur Framasoft, y compris en faisant des rafraichissements de la page. L'envoi est rapide (quoique...) mais le rafraichissement par Framasoft par forcément.
Ce que je comprend de ta fenêtre vide, c'est que tout est déjà parti et qu'il n'y a plus de différence !

[Thierry]

Après réflexion, peut être qu'il y a une autre cause... Profitons en pour continuer le tuto.

Tuto Partie 4 : Mise à jour du dépôt distant

Si vous avez utilisé le bouton 'Commiter' (et pas le 'Commiter & Pousser'), vous avez poussé vos modifications dans le dépôt local. Mais comment les envoyer ensuite vers le dépôt distant ?

A côté du bouton 'Commiter' dans la barre d'icônes du haut de la fenêtre principale, il y a une flèche bleue vers le bas qui permet de récupérer la version distante, puis une flèche vers le haut pour pousser le dépôt local vers le dépôt distant. C'est cette icône qui va nous aider.



Elle ouvre une fenêtre qui demande vers quelle branche de quel dépôt les modifications doivent être poussées. En général, il suffit de cliquer directement dur le bouton 'Pousser', et pouf, c'est parti !



Ici le dépôt distant s'appelle 'origin' (nom par défaut) et les branches s'appellent 'master' aussi bien sur le dépôt local que le distant.

Mais qu'est ce que c'est que ces branches dont Git parle tout le temps ?

Sommairement, une branche est une version différente du projet sous un nom particulier. A un moment donné, une branche est créée parce que le développement prend une direction parallèle et a besoin de tester des idées, tout en bénéficiant du service de stockage et d'historique de Git. A l'instant t, vous avez donc la branche principale, appelée par défaut 'master', et une ou plusieurs branches annexes. Votre dépôt local est la copie d'une branche particulière, généralement encore 'master', mais il est possible de cloner une autre branche du même dépôt distant dans un autre répertoire, et de travailler dedans sans risque de collision avec la branche principale. Lorsque vous le décidez, il est alors possible de fusionner les branches pour repartir sur seulement la branche principale.



Dans cette vision de ma dernière bibliothèque 'Commanders' dont l'article est en cours d'écriture, sur la fenêtre principale de Git Extension, on voit que depuis le commit 'initial' tout en bas, qui correspond à la création du projet, jusqu'à la version 0.50, les commits se sont succédés sans coup férir. Et puis une branche a été créée, à un moment où j'ai dû ré-écrire une grosse partie du noyau de la bibliothèque. Je voulais alors tester une hypothèse... Entre temps, la version 0.60 est née suite à d'autres corrections sur la branche principale 'master', puis la branche 'serial' a été fermée et fusionnée avec la branche principale qui a repris sa petite vie...

[DDEFF]

Okkaaay 
J'ai tout cassé et tout recommencé : tout est bon maintenant

Merci Thierry