Comprendre Git

Tout le monde se secoue ! 

J’ai commencé (lundi 02 mai 2016 à 18h43) la rédaction d’un tutoriel au doux nom de « Comprendre Git » et j’ai pour objectif de proposer en validation un texte aux petits oignons. Je fais donc appel à votre bonté sans limites pour dénicher le moindre pépin, que ce soit à propos du fond ou de la forme. Vous pourrez consulter la bêta à votre guise à l’adresse suivante :

Merci !

Choix du titre et structure générale

Le choix du titre me fait penser directement à un contenu qui s’adresse à un public débutant-intermédiaire qui a déjà fait ses premiers pas avec l’outil, mais qui aimerait maintenant comprendre en détail ce qu’il fait et comment ça marche. Or, cela semble être un contenu adressé aux parfaits débutants qui n’ont même pas encore installé git si j’en crois les premières lignes.

D’un autre côté, je trouve que le titre correspond parfaitement dans la mesure où après avoir lu cette bêta, je me dis que le contenu peut très bien être utile à quelqu’un qui utilise déjà git en le « subissant » à copier ou en retenant les commandes, mais qui n’a jamais vraiment compris. Dans ce cas, on a sûrement une bonne base pour ce genre de débutants qui veut comprendre Git et arrêter de tâtonner dans l’obscurité avec.

Initialisation de votre premier dépôt

On peut peut-être privilégier git commit -m '[message]', ce qui évite l’ouverture d’un éditeur (surtout quand c’est Vim !), et donc ce qui évite de charger mentalement d’autant plus le lecteur qui n’est pas forcément déjà très à l’aise avec le terminal.

Commits

Le tutoriel choisit une voie classique en présentant le commit comme pierre angulaire de Git. J’ai rien à redire là-dessus, et je trouve que le travail de vulgarisation là-dessus est bien parti (surtout avec les schémas attendus).

Un peu de jardinage

Superbes illustrations

Une remarque au passage : sur les nouvelles version de git, il est conseillé d’utiliser git switch plutôt que git checkout pour changer de branche ou en créer une nouvelle (comme avec checkout -b qui devient switch -c)

Étant donné que checkout a quand même tendance à faire tout, c’est peut-être une bonne chose d’introduire swicth pour limiter la charge mentale. Surtout que le chapitre d’après montre encore d’autres usages de checkout.

C’est tout pour moi, pour le moment

Je suis loin d’avoir tout lu mais c’est prometteur !

Merci pour les retours !

Pour moi la cible est principalement ceux qui utilisent git sans comprendre. Je connais beaucoup trop de monde pour qui git est juste commit / push / pull ou une GUI et ne comprends pas ce qu’ils font (avec tous les problèmes que cela induit).

Je préfère donc partir de zéro et ne pas essayer de deviner ce que les lecteurs pourraient déjà connaitre. Ce qui peut effectivement le rendre accessible aux débutant complet, mais c’est tout aussi bien :D.

On peut peut-être privilégier git commit -m '[message]', ce qui évite l’ouverture d’un éditeur (surtout quand c’est Vim !), et donc ce qui évite de charger mentalement d’autant plus le lecteur qui n’est pas forcément déjà très à l’aise avec le terminal.

Effectivement. Je vais quand même laisser le passage sur vim au cas où quelqu’un essayerai de taper git commit directement…

Superbes illustrations

C’est ma femme qu’il faut remercier pour cette partie .

Une remarque au passage : sur les nouvelles version de git, il est conseillé d’utiliser git switch plutôt que git checkout pour changer de branche ou en créer une nouvelle (comme avec checkout -b qui devient switch -c)

J’avoue que je n’utilise jamais switch et que je ne l’ai jamais vraiment vu utilisé non plus. Je laisserai checkout mais en ajoutant une note sur switch. Peu de personne connaissent vraiment switch et demander de l’aide sur checkout sera surement plus aisé actuellement.

À noter qu’il y a aussi git restore pour remplacer certaines fonctionnalités de reset / checkout. Mais je ne trouve pas que rajouter une commande de plus avec ses propres options soient vraiment pertinent pour une introduction à la compréhension de git.

Je pose ça là.

Sinon je n’ai pas encore eu le temps de lire ton tuto, donc je n’ai pas encore d’avis dessus. Mais je ne peux qu’appuyer l’initiative.

Pour moi la cible est principalement ceux qui utilisent git sans comprendre. Je connais beaucoup trop de monde pour qui git est juste commit / push / pull ou une GUI et ne comprends pas ce qu’ils font (avec tous les problèmes que cela induit).

Je préfère donc partir de zéro et ne pas essayer de deviner ce que les lecteurs pourraient déjà connaitre. Ce qui peut effectivement le rendre accessible aux débutant complet, mais c’est tout aussi bien :D.

Ok, ça se défend et dans ce cas je pense que le tutoriel a pour l’instant un rythme et un style qui reste cohérent avec ce niveau que tu vises. (j’avoue ça m’aurait semblé un peu abrupte si ça avait été pour le parfait débutant total)

J’avoue que je n’utilise jamais switch et que je ne l’ai jamais vraiment vu utilisé non plus. Je laisserai checkout mais en ajoutant une note sur switch. Peu de personne connaissent vraiment switch et demander de l’aide sur checkout sera surement plus aisé actuellement.

C’est vrai, c’est vraiment sur les toutes dernières versions de git, et même pas sûr que toutes les distributions l’incluent déjà

Installation et initialisation de votre premier dépôt

Dans la section Configurer Git, tu recommandes d’exécuter $ git config --global core.editor nano mais plus loin, quand tu parles de git commit, tu parles de vim. Si quelqu’un a suivi ton conseil, il ne verra pas vim mais nano.

Un peu de jardinage

Sur le schéma "Commit casque bleu !", pourquoi y a-t-il un sparadrap sur le commit de la branche plutôt que sur celui de master?

Quand tu parles de git rebase, tu dis "Il n’y aura ainsi plus de conflit lors de la fusion de la branche secondaire dans la principale." mais directement après, tu montres un exemple de git rebase avec conflit. Ce n’est pas très clair ce que tu veux dire par là. Je pense que quand on parle de git rebase, il est important de préciser qu’il va modifier l’historique en "insérant" les commits au bon endroit dans la branche vers laquelle on rebase.

Quand tu parles de HEAD, ce serait bien de donner un peu plus d’explication que "HEAD fait une seul chose, il nous indique l’endroit où nous nous trouvons actuellement". Si je ne m’abuse, on peut voir HEAD comme un pointeur vers un commit et on peut faire bouger ce pointeur en utilisant git checkout. Ca peut aider à visualiser d’expliquer ça. Tu peux aussi voir où est HEAD en utilisant git log. Je trouve toujours ça utile personnellement.

miguel@laptop:/home/Miguel/Codes/test$ git log
commit b207db0eaeaa51cfdeb8634a1f880c84fac3d4b2 (HEAD -> master)
...

Retour vers le futur

Concernant le detached HEAD, quand tu fais git checkout vieuxCommit, git te prévient déjà que tu es en detached head, pas besoin de faire de git status.

Il serait bon de mettre un gros warning autour de git reset car si il est utilisé sans y réfléchir convenablement, il peut avoir des effets désastreux.

L’attaque des clones

Avant de proposer de faire un fetch du dépôt zds, je pense qu’il faudrait conseiller de créer un nouveau dossier sinon c’est perturbant (et pas du tout réaliste) d’avoir sa propre branch master qui n’a absolument rien à voir avec les branches qu’on vient de fetch. La partie sur les dépôts distants est un peu rapide et pas très élaborée je trouve. Il faudrait expliquer la différence entre git fetch et git pull, le concept d’origin, parler de git pull —rebase, etc.

Divers

Je pense que quelque part, il serait bon d’expliquer les différences majeures entre git et les autres gestionnaires de version comme SVN ou Mercurial.

En dehors de ça, j’aime beaucoup l’approche avec les exemples pratiques qui permettent de bien voir ce qu’il se passe ainsi que les schémas pour bien visualiser.

Salut,

J’ai fait le tour du tutoriel que j’ai trouvé pas mal, en plus c’est écrit par deux Pikachu !
Dans la suite du message je reporte les différentes remarques que j’ai pu me faire selon les chapitres. J’ai aussi relevé des petites fautes d’orthographe dont je fournis une liste par chapitre.

Installation et initialisation de votre premier dépôt

Au long du tutoriel on comprend que git va permettre de travailler à plusieurs, mais comment concrètement ? Quel est le but ? Qu’est-ce qui va faire qu’il sera plus facile de travailler à plusieurs sans se marcher dessus ?

Aussi est-ce que vous pourriez présenter les pré-requis nécessaires pour suivre le cours ? Je pense notamment au shell Linux.

Historique

Je trouve la phrase sur Linux assez ambiguë (« Si vous vous intéressez à Git, vous connaissez surement Linux. Son développement est assuré par toute une équipe, et n’importe qui peut proposer des patchs. »). Après l’avoir lue je n’ai pas compris que vous parliez du code de Linux et pas de celui de git.

Peut-être qu’il serait aussi préférable d’utiliser un terme plus générique que « mailing list » qui ne sera pas forcément compris de tout le monde.

Configurer git

Je n’ai pas trouvé très logique de faire configurer le nom / email avant même de créer un premier dépôt ou un premier commit, ça a l’air de sortir de nulle part.
À ce moment-là la configuration est globale, mais il ne serait de toute façon pas possible de faire une configuration locale car aucun dépôt n’existe.

Initialisation de votre premier dépôt

Je ne suis pas très sûr que ce soit le lieu pour parler de vim, un autre éditeur ne pourrait pas être utilisé dans git bash ? En plus, comme relevé par @Migwel, vous configurez nano comme éditeur par défaut juste avant.

Et je rejoins @sgble sur le fait que ce serait cool de montrer commit -m tout de suite.

Vous pouvez à tout moment voir l’état actuel de votre dépôt

Qu’est-ce que l’état d’un dépôt ? Je pense que des explications seraient bienvenues.

Corrections orthographiques

• « vous récupérerz »
• « et refaites »
• « ils ont décidés »
• « ils ont d’abord décidés »
• « BitKeeper finit par »
• « les mêmes principes »
• « un des principaux systèmes »
• « ouvrez […], puis taperz »
• « deux commandes essentielles »
• « seront donc bien évidemment différents »

Une histoire de commit

Je trouve encore une fois que ça manque de concret. On crée des commits qui ne contiennent pas grand chose, dans des fichiers un peu inutiles. Mais ça ne répond pas vraiment à la question de fond : à quoi ça sert un commit ?

Un commit

Vous nommez le premier commit 7a7c. C’est une notation valable mais est-ce que ce serait pas mieux d’utiliser les 8 premiers caractères du hash plutôt que seulement 4, pour rejoindre la notation généralement utilisée ?

Des commits

Rien à redire si ce n’est que vivement l’arrivée des schémas !

Soyons fainéants

J’aurais pensé que la section parlerait de git diff --staged pour bien illustrer les différentes zones.

Retrouvons Coco

On voit apparaître un tag Coco2 dans les logs git, c’est une erreur suite à un renommage ?

Corrections orthographiques

• « toutes les modifications »
• « ce que renvoite »
• « Chaque ligne précédée »
• « Le reste concerne le fichier concerné » → répétition
• « les fichiers modifiés »
• « les fichiers ajoutés (on dit aussi indexés) »
• « touts les fichiers »
• « les fichiers nouvellement créés (tels que »
• « ne faisant pas partise »
• « valide ses changements » → et peut-être « ces »
• « bien suûr »
• « Les derniers commits sont affichés »
• « Il est effectivement plus utiles »
• « quinze commits différents »
• « de notre dépôts »
• « sont très pratiques »

Un peu de jardinage

Une nouvelle amitié qui commence

Les concepts de file et de bifurcation sont entremêlés dans l’introduction, on ne comprend pas nécessairement bien qu’un commit puisse apparaître dans deux files (branches) ni que des branches peuvent bifurquer puis se rejoindre (impossible avec des files).

Je pense aussi qu’il serait bon de présenter git switch comme alternative au checkout.

Les blocs de code sont un peu trop compacts et donc difficiles à suivre, peut-être faudrait-il les séparer en plusieurs blocs ? Ça permettrait d’ajouter quelques commentaires au passage.

L’email n’est pas masqué dans tous les exemples.

Certaines images ont des problèmes de résolution pour les pancartes des branches ce qui les rend difficiles à lire.

Fuuuuuuu-sion !

La section ne précise pas que deux branches peuvent modifier un même fichier sans que cela ne mène à des conflits, si les lignes impactées sont suffisamment distinctes pour que git s’y retrouve (et donc que c’est géré par la fusion automatique).

Le code sur le rebase est difficile à suivre, on voit les commandes sans comprendre ce que vous voulez faire, le rebasage n’est pas vraiment expliqué. Ça mériterait peut-être une section à part, et je pense que les schémas gagneraient à être présentés avant le code pour expliciter ce qui va être fait. Et des schémas étape par étape permettrait de découper et aérer les blocs de code.

Le super-héro de Git

On voit ^ et ~ utilisés mais pas vraiment expliqués, le seront-ils par la suite pour présenter leurs différentes possibilités ?

Corrections orthographiques

• « Une branche àa toujours un nom »
• « les autres utilisateurs du dépôt travaillent »
• « la fonctionnalité terminée »
• « Comment allons nous fusionner sces branches ? »

Retour vers le futur

Récupérer un fichier

On ne comprend pas forcément le checkout, il n’est pas dit d’où le fichier est récupéré, et que les modifications non validées sont effacées.

Les univers parallèles

Encore une fois difficile à suivre sans exemples concrets. Est-ce qu’il ne pourrait pas y avoir un petit projet plus réaliste pour décrire les étapes ?

Par exemple vous pourriez présenter le git correspondant à la rédaction d’un contenu sur ZdS.

Remise à zéro

Peut-être qu’il faudrait montrer des exemples d’utilisation où l’on revient sur des commits particuliers plutôt que sur HEAD. Et présenter quelques cas d’usage où reset pourrait être utile.

git reflog

Le cas d’usage est pertinent, peut-être qu’il faudrait juste remplacer [COMMIT] par l’id du commit dans l’exemple pour bien montrer ce qu’on souhaitait retrouver et où est écrite l’info dans le résultat de la commande.

Corrections orthographiques

• « les modifications effectuées »
• « n’importe quelle fichier »
• « c’est quand meême fatiguant de récupérer tout ses fichiers » → et peut-être « ces » à la place de « ses »
• « touts les fichiers d’un commit »
• « ce qui nous permets »

L’attaque des clones

Échange de données

Ça manque un peu d’explications autour de l’option -a de git branch.

Clonage

Je trouve que le git clone arrive tard dans le processus. Un dépôt d’exemple pourrait être fourni, à cloner dès le début du tutoriel : c’est plus comme ça que ça se passe en vrai que par un git init.

Corrections orthographiques

• « vous le faites »
• « manière décentralisée »
• « l’authentification pouvant être facilitée »
• « les dépôts distants »
• « l’envoise »
• « À notezr »
• « entre les branches locales et distantes »
• « une branches »
• « la copie locale »
• « Il faut pensezr »
• « beaucoup de choses »

Voilà pour moi !