Ce document a été rédigé par et pour les équipes de Headcrab. C'est un guide d'aide et d'utilisation de Git et GitHub, ainsi que de certaines bonnes pratiques suivies par les collaborateurs de l'entreprise.
Il n'est pas exhaustif, et ne dispence pas de demander de l'aide à ses collègues.
Ce document avait initialement un usage interne exclusivement, est était donc destiné à un public averti. Il devait servir de rappel pour les développeurs, et de base de connaissance pour les autres métiers (Game Designers, Graphistes, QA testers...). Il est donc possible que certaines informations aient été omises, ou que certains concepts soient compliqués à comprendre et / ou pas assez approfondis ici.
Ce document a pour but d'expliquer dans les grandes lignes comment utiliser GitHub Desktop et GitHub.
Une fois que vous aurez lu ce document, nous vous recommandons d'aller lire le Gitflow Workflow au moins jusqu'à la partie Release Branches (incluse), car c'est le workflow que nous utilisons.
- Installation
- Utiliser GitHub Desktop
- Utiliser le site GitHub
- Fonctions avancées de git en ligne de commande
Téléchargez GitHub Desktop pour votre machine, et installez le.
Créez un compte github, ou connectez-vous avec votre compte existant afin de pouvoir continuer.
Présentation de l'interface :
- Explorateur de projets
- C'est ici que vous choisissez le projet sur lequel vous voulez travailler.
- Explorateur de fichiers
- Les modifications entre votre projet, et le projet en ligne apparaissent ici ;
- Si vous ajoutez un fichier dans le projet, il apparaîtra avec un + vert ;
- Si vous modifiez un fichier existant en ligne, il apparaîtra avec un • orange ;
- Si vous supprimez un fichier qui était en ligne, il apparaîtra avec un - rouge.
- Gestion du commit
- La première case contient le titre du commit. (Ici "Update Player.cs") ;
- La deuxième case sert à la description du commit. (Ex : "Change z position of spawned projectile").
- Explorateur de branches
- C'est ici que vous choisissez sur quelle branche du projet vous voulez travailler ;
- On ne travail jamais sur develop ou master. JAMAIS.
- Bouton Fetch
- Ce bouton affiche Fetch afin de vérifier si des modifications son présentes en ligne ;
- S'il y a du nouveau en ligne, il va se transformer en Pull pour récupérer les modifications, et mettre votre version locale à jour. (Un indicateur du nombre de commits à récupérer s'affiche à côté du bouton) ;
- Si vous avez des modifications commits en attente, il va se transformer en Push pour envoyer vos modifications sur le serveur distant.
- Explorateur des modifications
- Cette case affiche les modifications entre la version en ligne et votre version, du fichier sélectionné dans l'explorateur de fichiers ;
- Sur la version actuelle, on peut voir que j'ai modifié les lignes 305 et 311 ;
- En rouge la ligne qui a été supprimée ;
- En vert la ligne qui a été ajoutée. (Modification du "0" en "10").
Cette partie explique comment utiliser les fonctions principales de GitHub Desktop.
Si c'est la première fois que vous lancez GitHub Desktop, 3 choix s'offrent à vous.
- Clone a repository from the Internet
- Cette option permet de récupérer un projet sur lequel vous travaillez, ou un projet public ;
- Si vous travaillez sur un projet, il apparaîtra dans l'onglet GitHub.com. Il ne vous reste plus qu'à le sélectionner et choisir où vous voulez le cloner ;
- Si vous voulez récupérer un projet public, allez dans l'onglet URL et renseignez l'url du projet ;
- Il ne vous reste plus qu'à cliquer sur Clone pour lancer le téléchargement du projet.
- Create a New Repository on your hard drive
- Cette option vous permet de créer un nouveau projet que vous pourrez ensuite héberger sur github.
- Add an Existing Repository from your hard drive
- Cette option permet de rajouter dans GitHub Desktop un projet que vous avez téléchargé précédemment sans utiliser l'application Desktop.
Pour cloner un projet depuis une url, cliquez sur le bouton vert Clone or download sur la page github du projet, puis copiez l'url.
Si vous avez déjà des projets dans GitHub Desktop, il vous suffit de cliquer sur le bouton Add dans l'explorateur de projets.
Pour créer une branche, rien de plus simple. Dans l'explorateur de branches, cliquez sur New branch à droite de la case Filter.
N'oubliez pas de nommer votre branche en suivant la convention. (fix/#xx, implement/my-fonction, ...)
Si vous avez des changements qui n'ont pas été commit au moment de la création de branche, vous aurez la possibilité de les déplacer sur votre nouvelle branche (utile si on a oublié de changer de branche avant d'entamer des changements), ou les laisser sur votre branche précédente.
Vous serez ensuite déplacé sur la branche que vous venez de créer.
Un commit sert à sauvegarder vos modifications à un instant T.
À tout moment (pensez à le faire régulièrement), vous pouvez créer une "photo" de vos modifications à un instant précis, avec un titre et une description. Plus vous faites de commits, plus il sera simple de revenir en arrière si un problème se présente.
Il n'est toutefois pas nécessaire de faire un commit à chaque fois que vous modifiez une ligne, le mieux est l'ennemi du bien.
Un commit à chaque fois que vous effectuez une sous-tâche de votre feature ou votre fix est suffisant.
Une fois que votre commit est sauvegardé localement (quand vous avez appuyé sur "Commit to yourBanch"), le bouton Fetch devient Push et le nombre de commit à envoyer au serveur augmente.
Notez que les commits sont sauvegardés localement. Tant que vous ne pushez pas un commit, vous pouvez l'annuler (pour modifier son contenu, ou son titre / description) à volonté. (Attention, le revers de cette "liberté" est que vous pouvez perdre vos modifications locales en cas de problème avec votre machine).
Vous n'êtes pas obligé de push directement chaque commit. (Parfois on se souvient qu'on a oublié d'enlever un Debug.Log juste après le commit). Cela permet de pouvoir modifier ce commit au besoin. Cependant, n'attendez pas non plus d'avoir fini votre feature de 4000 commits. Si votre disque dur vous lâche, tous les commits non push seront perdus, et donc à refaire.
Pour se déplacer d'une branche à l'autre, il vous suffit de sélectionner la branche que vous voulez depuis l'explorateur de branches.
De la même façon qu'à la création de branche, si vous switchez de branche en ayant des modifications non commit, GitHub Desktop vous proposera de les déplacer avec vous ou de les laisser sur la branche que vous quittez.
Si vous comptez laisser vos modifications sur la branche que vous quittez, pensez à les commit (pas besoin de les push, vous pourrez undo le commit plus tard) pour ne pas qu'elles aillent dans la partie Stashed Changes et qu'elles puissent être écrasées.
Pour supprimer vos modifications en cours, plusieurs possibilités. Si vous voulez tout supprimer, le plus simple est de faire un clique droit sur X changed files en haut de l'explorateur de fichiers, puis Discard all changes.
Si vous souhaitez supprimer uniquement certains fichiers, sélectionnez les dans l'explorateur de fichiers, puis faites un clique droit sur l'un d'entre eux, Discard X selected files. (Ou Discard changes s'il n'y a qu'un fichier).
Il arrive que des conflits se créent quand des fichiers sont modifiés sur plusieurs branches en même temps.
Si une ligne est modifiée dans une branche, et la même ligne est modifiée autrement dans une autre branche, git ne sait pas laquelle des deux il doit choisir. Il crée donc un conflit.
Si un conflit sauvage apparaît, à défaut de le capturer avec un pokéball, GitHub Desktop vous proposera de l'ouvrir dans Visual Studio Code (si ce dernier est installé sur votre machine) afin de le résoudre.
Si vous décidez de le résoudre avec VS Code, ce dernier s'ouvrira, et surlignera les lignes conflictuelles.
Il y a ensuite un séparateur : =======
Puis les modifications de la branche que vous essayez de récupérer, en bleu avec l'inscription ">>>>>>> branchName (Incoming Change)".
Sur l'exemple ci-dessus, les modifications ne sont pas importante. On a juste changé la vitesse du joueur. Si vous savez quelle version vous souhaitez garder, il vous suffit de cliquer sur Accept Current Change ou Accept Incoming Change (au dessus de la ligne verte) pour garder respectivement vos modifications, ou les changements sur de l'autre personne qui a travaillée sur le fichier, et supprimer l'autre version.
L'option Accept Both Changes permet de garder les 2 versions, l'une au dessus de l'autre. Cela peut être utile dans le cas où vous avez besoin de certaines modifications de la branche actuelle, et certaines autres de la branche entrante. (Ce n'est pas le cas sur l'exemple actuel, mais ça pourrait l'être dans une fonction où 2 personnes ajouteraient des lignes distinctes et utiles).
L'option Compare Changes affiche les 2 fichiers (votre version et celle modifiée par une autre personne) côte à côte afin de comparer les modifications plus facilement.
Utiliser le site GitHub
La création d'issue est un moyen simple d'informer toutes les personnes impliquées dans un projet d'un un bug, un point à améliorer, etc...
Quand vous découvrez un nouveau bug, pensez bien à créer un ticket.
Pour créer un ticket, rien de plus simple. Allez dans la partie Issues du projet, puis cliquez sur le bouton vert New issue.
Les tickets doivent avoir un nom simple MAIS décrivant l'issue.
N'hésitez pas à rajouter une description la plus claire possible pour expliquer comment reproduire un bug, ou quelle genre de feature devrait être ajoutée.
Un template de ticket peut être existant afin de faciliter leurs créations.
À droite de la partie rédaction de votre issue se trouve plusieurs options :
- Assignees
- C'est la ou les personnes qui sont en lien avec cette issue. Si vous connaissez la ou les personnes relatives à ce ticket, n'hésitez pas à les assigner.
- Labels
- Différents mots clés afin de savoir de quoi parle le ticket (et de pouvoir les filtrer). N'hésitez pas à mettre un label à votre ticket s'il y en a un qui lui correspond.
- Project
- Permet d'assigner un ticket à un projet existant.
- Milestone
- Permet de donner une échéance avant laquelle le ticket doit être clos. (Ne fonctionne que si des milestones ont été crées).
Pensez à fixer régulièrement des tickets. Mieux vaut en faire quelques uns de temps en temps, plutôt que de se retrouver avec 800 fix à faire à la fin de la semaine.
Ce n'est pas parce qu'un ticket est assigné à une autre personne que vous ne pouvez pas vous en occuper. Si un ticket vous inspire et que vous souhaitez le corriger, n'hésitez pas, après vous être assuré que la personne assigée ne travaille pas déjà sur la tâche (être 2 sur la même tâche == conflits git et perte de temps).
Pensez à noter le numéro du ticket que vous corrigez dans le nom de la branche sur laquelle vous allez travailler. (Un #XX permet d'accèder au ticket en cliquant sur son nom. Cela marche dans les noms de branches, les noms de commits, les descriptions de commits, les commetaires, etc...)
Quand une pull request contenant le nom "fix #XX" est merge, en temps normal le ticket associé se ferme également.
Si ce n'est pas le cas, à vous d'aller fermer votre ticket manuellement en appuyant sur le bouton Close issue.
C'est toujours bien de rajouter un commentaire du style "fix with #XX" (où #XX représente le numéro de la pull request) si le lien entre les deux ne s'est pas fait automatiquement.
La force de git réside dans 2 points. Le premier est le fait de conserver un historique de votre travail, ce qui permet de revenir facilement à des versions antérieurs en cas de problème. Le deuxième est la possibilité qu'il offre de travailler facillement à plusieurs, sur le même projet. Ce deuxième point est permis en partie grâce aux pull requests.
Une pull request permet de controler des modifications avant des les ajouter à une branche.
Une fois que vous avez fini votre feature de mouvements du joueur, et que celle-ci a été TESTÉE et VALIDÉE, il faut que tout le monde puisse accèder à cette feature. C'est pourquoi vous voulez fusionner votre branche feature/player-movements dans develop.
Pour créer une pull request, rien de plus simple, il suffit d'aller dans la partie Pull requests de votre projet git, puis de cliquer sur le bouton vert New pull request.
À partir de là, vous attérirez sur une page où vous devez choisir les branches que vous voulez fusionner.
La branche de gauche représente la destination, la branche qui va accueillir les nouveautés. Dans notre exemple, ce serait develop.
La branche de droite représente la source, la branche qui va envoyer ses modifications. Dans notre exemple, ce serait votre branche feature/player-movements.
Vous pouvez ensuite cliquer sur le bouton vert Create pull request pour la créer.
En dessous s'affiche les différences entre la branche source et la branche cible.
- Les différents commits de la branche source qui vont être ajoutés (leurs numéros, titres, descriptions) ;
- Les fichiers qui ont été modifiés (avec la possibilité de les visualiser, les commenter, les contester, etc...) ;
- Les commentaires présents sur les différents commits s'il y en a ;
- Les contributeurs de ces modifications.
Une fois que vous avez ouvert une pull request, vous ne devez JAMAIS la merge tant qu'elle n'a pas été validée.
Pour ce faire, il faut qu'un autre utilisateur fasse une review de votre pull request (c'est à dire vérifier et valider les modifications). Vous devrez également faire des reviews des pull requests des autres membres.
Pour faire une review, sélectionnez une pull request ouverte, et allez dans l'onglet Files changed. (Vous pouvez utiliser le filter pour cacher les fichiers qui ne peuvent pas être revu (images, meta, ...))
A partir de là, il faut lire le code de la personne.
Le but est de s'assurer qu'il n'y a pas de coquilles, des commentaires inutiles, des Debug.Log qui trainent. Que le code respecte les guidelines.
De plus cela permet d'apprendre énormement. C'est pour cela qu'il ne faut pas hésiter à proposer des solutions si quelque chose dans le code vous semble farfelu. Vous avez la possibilité de commenter les lignes de code directement en cliquant sur le + bleu à gauche de la ligne désirée.
Une fois que vous avez fini la relecture du code, il vous faudra cliquer sur le bouton vert Review changes en haut à droite.
A partir de là, 3 possibilités :
- Comment
- Si vous avez un commentaire à faire sur les changements.
- Approve
- Valide la pull request. Si vous la validez, n'importe quel utilisateur pourra la merge avec la branche de destination, à n'importe quel moment.
- Request changes
- Vous ne validez pas la pull request, et indiquez que des changements doivent être effectués (en général si vous cliquez sur ce bouton, vous avez aussi laissé un/des commentaire(s)).
Une fois votre choix fait, il ne vous reste plus qu'à cliquer sur Submit review.
Une fois qu'une review a été faite sur votre pull request, 2 possibilités.
- Votre pull request à été refusée
- Dans ce cas, vous modifiez le titre pour rajouter "WIP" au début de celui-ci. Cela indique que vous travaillez dessus, qu'il ne faut pas la merge ou faire de review pour l'instant.
- Votre pull request a été validée
- Il ne reste plus qu'à cliquer sur le bouton merge en bas de la page, et supprimer ou non la branche source, en fonction de si vous allez continuer à travailler depuis cette branche ou non.
Cette partie donne les commandes les plus utilisées en ligne de commande.
La plupart du temps, GitHub Desktop suffit largement. Cependant les commandes git offrent beaucoup plus de liberté. Elles ne sont pas obligatoire, donc cette section sert principalement de rappel.
Vous pouvez retrouver toutes les commandes dans la documentation de git.
- git branch nomDeLaBranche -> pour créer une nouvelle branche nommé
nomDeLaBranche. - git checkout nomDeLaBranche -> pour changer de branche localement.
- git checkout -b nomDeLaBranche -> pour créer une branche locale
nomDeLaBrancheet se placer dessus. (Revient à faire ungit branchpuis ungit checkout.) - git fetch -> récupère les modifications présentes sur le serveur, qui ne sont pas sur votre machine.
- git merge -> applique les changements récupérés sur le serveur, sur votre branche locale.
- git pull -> fait automatiquement un
git fetchpuis ungit merge. Récupère les changements distant et les appliques sur votre branche locale en une commande. - git pull origin nomDeLaBranche -> merge les modifications présente sur la branche remote
nomDeLaBranchedans votre branche locale. Par exemple, si vous voulez résoudre des conflits empêchant un merge de votre branche dans devolop, vous pouvez fairegit pull origin developpour appliquer les changements de develop dans votre branche, puis résoudre les conflits et les pousser. - git add nomDuFichier -> pour ajouter le fichier
nomDuFichierau prochain commit. - git add . -> pour ajouter tous les changements locaux au prochain commit.
- git commit -m "Ce commit contient tel changement" -> pour créer un commit local de vos modifications.
- git push -u origin nomDeLaBranche -> pour envoyer une branche local sur le serveur distant.
- git push -> pour envoyer les commits locaux sur le serveur.
- git stash -> pour sauvegarder vos modifications dans un coin et remettre votre espace de travail à l'état précédent les modifications stash.
- git stash pop -> pour restaurer le dernier stash.
- git cherry-pick numeroDeCommit -> pour récupérer un commit précis, sans avoir à récupérer ceux d'avant ou ceux d'après.
- git commit --amend -m "Nouveau message de commit" -> permet de modifier un message de commit déjà push (évitez d'utiliser cette commande sur un commit utilisé pour créer une branche)
Si vous souhaitez récupérer les changements en contrôlant le moment ou git va les merge localement faites plutôt comme cela.
- git fetch -> récupère les changements distant depuis le serveur ;
- git merge -> fusionne les changements récupérés avec votre travail local. Vous pouvez utiliser l'option --no-ff pour créer un commit de merge ce qui est potentiellement plus propre et facilite le revert de tous vos changements sur la branche si une erreur s'est glissée dans vos commits.
Vous pouvez désactiver le fast forward de façon permanante en modifiant votre fichier de configuration git comme cela.
[merge]
ff = no
commit = no
[pull]
ff = yes
Pour ce qui est de rebase (ce qui permet d'avoir une historique plus linéaire, ce n'est cependant pas à faire tout le temps) on utilisera les commandes suivantes :
- git rebase laBrancheDeDestination ;
- git checkout laBrancheDeDestination ;
- git merge maBrancheAFusionner.
Pour rebase au moment où on pull on peut également faire :
- git pull --rebase -> ce qui permet de replacer la branche courante à la suite de l'upstream.
Pour squasher les commits et avoir un historique plus propre (par exemple vous avez fait 3 commits, mais les deux premiers servent à fix le même bug, ce qui au final peut se résumer en 1 seul commit pour plus de clarté) :
- git rebase -i HEAD~3 -> va vous permettre en mode interactif d'éditer vos 3 derniers commits.
Pensez à rajouter la ligne suivante dans votre fichier de configuration de git afin de choisir LF comme line ending.
(Le choix peut vous être proposé lors de l'instalation de git)
[core]
autocrlf = false
(ou exécutez cette commande dans votre terminal)
git config --global core.autocrlf false
CRLF et LF ont chacuns leurs avantages, cependant nous préfèrerons LF pour 3 raisons principales
- LF est cross-platform Unix / Windows ;
- Certains outils et systèmes de versionning préfèrent LF ;
- On gagne un octet par ligne. Ridicule sur un petit projet, mais non négligeable sur un projet de taille industrielle.
Il existe des extensions pour Visual Studio et Visual Studio Code.
Git History (VS Code)
Git Lens (VS Code)
GitHub extension for visual studio (Visual Studio)
There is an English version of this How to use GitHub and GitHub Desktop ?
Je cherchais un article qui explique git simplement pour commencer parce que je ne sais pas du tout l'utiliser.
Celui-ci me paraissait bien au premier coup d’œil... Mais, en le lisant, j'ai trouvé d'abord que c'était bourré de fautes d'orthographe avec des erreurs syntaxiques, de ponctuations, etc... C'est dommage parce que c'est bien construit mais je ne suis pas encore prête à utiliser git après cette lecture. Il ne manque pas grand chose, juste des explications supplémentaires, le schéma des branches n'est pas clair, du vocabulaire de programmeur non expliqué et d'autres petites choses qui mériteraient d'être exploitées.
Mais ce genre d'article est très utile pour ceux qui découvrent et qui ne veulent pas être assommés de pavés indigestes.
Merci quand même pour cet éclairage.