Le guide Git de Beej

• Une page de guide qui propose des versions HTML et PDF en plusieurs formats pour les lecteurs souhaitant apprendre Git ou s’y référer
• Le guide part du principe qu’il peut contenir des erreurs ; les corrections concernant des informations Git erronées sont acceptées par e-mail
• Les versions HTML peuvent être choisies selon l’environnement de lecture : version découpée, page unique, widescreen, ZIP, etc.
• Les PDF sont téléchargeables en combinaisons US Letter ou A4, recto ou recto verso, avec coloration syntaxique ou en noir et blanc
• Les traducteurs et auteurs peuvent cloner l’ensemble des ressources depuis GitHub, puis travailler en suivant le README

---

Formats de distribution pour la lecture

• HTML

  • HTML
  • HTML, widescreen
  • HTML, single page
  • HTML, single page, widescreen
  • HTML ZIP
  • HTML ZIP, widescreen

• PDF

  • US Letter, recto, coloration syntaxique
  • US Letter, recto verso, coloration syntaxique
  • A4, recto, coloration syntaxique
  • A4, recto verso, coloration syntaxique
  • US Letter, recto, noir et blanc
  • US Letter, recto verso, noir et blanc
  • A4, recto, noir et blanc
  • A4, recto verso, noir et blanc

Suggestions de correction et ressources de travail originales

• Le guide laisse ouverte la possibilité qu’il contienne des erreurs, et les suggestions de correction sont reçues par e-mail
• Les traducteurs et auteurs peuvent cloner le dépôt GitHub et suivre le README

[GN⁺]

Avis sur Hacker News

• Si vous trouvez une erreur, signalez-la. Je ferai le tri et corrigerai moi-même — Beej

  • Ce n’est pas vraiment une erreur, mais si l’on parle de vim dans le contexte de Git, :cq mérite aussi d’être mentionné. Cela permet de quitter avec un code de sortie non nul, afin d’empêcher Git de terminer le commit ou l’opération en cours
  • Vraiment excellent travail, et merci d’avoir produit une ressource aussi complète. Je n’ai pas tout lu, mais une formulation dans la section 5.1 m’a sauté aux yeux
    Dans https://beej.us/guide/bggit/html/split/branches-and-fast-for..., il est dit que « la branche par défaut est main » et qu’« autrefois c’était master, et certains anciens dépôts ont encore master », mais ce n’est pas exact. Git utilise toujours master par défaut, et permet simplement de changer cela pour les futurs git init via git config --global init.defaultBranch
    Source : https://github.com/git/git/blob/bc204b742735ae06f65bb20291c9...
    De plus, parler d’« anciens dépôts » envoie un mauvais message. C’est GitHub qui a décidé ce changement, d’autres ont suivi, et Git lui-même a fini par autoriser le réglage mentionné plus haut ; ce n’est donc pas vraiment une question de dépôts récents ou anciens, mais plutôt de préférence
  • J’ai été l’un des nombreux étudiants passés par Lambda School, et ce cours a été l’un des moments les plus marquants de cette période
  • J’ai lu le guide de programmation en C quand j’étais ado, et aujourd’hui, en tant que développeur firmware, j’ai toujours l’impression d’avoir une grande dette envers lui
  • Ce n’est pas une erreur non plus, mais git worktree mérite aussi d’être mentionné. C’est devenu central dans mon workflow, et beaucoup de gens ignorent même son existence
    C’est un bon moyen de garder des branches bien séparées sans avoir à gérer les complications de stash

• Beej's Guide to Network Programming et Beej's Guide to Unix IPC, que j’ai lus ado, étaient à la fois accessibles et profonds, et ont beaucoup influencé le programmeur que je suis devenu par la suite
  [0] https://beej.us/guide/bgnet/
  [1] https://beej.us/guide/bggit/

  • [1] correspond à https://beej.us/guide/bgipc/
  • Pareil pour moi. J’étais ado au milieu des années 90, et j’étais fasciné par le code des serveurs IRCd et les bots
    J’avais acheté d’occasion Slackware Linux Unleashed avec son CD-ROM, qui contenait des exemples de réseau en C ; comme ce code me laissait perplexe, j’ai fini par trouver le site de Beej sur le réseau. De là, je me suis enfoncé encore plus profondément dans le terrier du lapin, et je faisais le tour des librairies pour trouver des livres de programmation
    Après avoir acheté l’excellent ouvrage de référence de Richard Stevens, je n’ai jamais regardé en arrière, et je suis encore reconnaissant à Beej d’avoir rendu cette passion possible
  • Je me souviens avoir traduit en italien le guide réseau de Beej à l’époque où j’apprenais à utiliser select, parce que je voulais rendre un scanner de ports, peut-être « grabb » ?, plus rapide. C’était le bon temps
  • Je suis venu vérifier si c’était la même personne, et en voyant ce vieux design web où chaque page avait sa personnalité, j’en ai été presque certain
    C’était l’époque où je sauvegardais les pages pour les lire hors ligne afin que mon père ne s’énerve pas à cause de la facture de téléphone ; quand le code fonctionnait, cela ressemblait à une validation qui faisait oublier les échecs et rejets précédents de la vie. Le plaisir d’envoyer un message d’un ordinateur à un autre était immense

• En voyant « ancienne commande : git checkout », je ne savais même pas que git switch existait, ni que git checkout était considéré comme une vieille alternative. Je me sens vieux
  J’ai commencé à apprendre Git il y a presque 10 ans, donc soit, mais c’est étrange de se dire que quelqu’un qui apprend Git aujourd’hui pourrait être dérouté par le fait que j’utilise git checkout. J’ai l’impression d’employer une tournure démodée
  Pour revenir au texte, ce guide m’aurait été vraiment utile quand j’apprenais. Il est facile à suivre et couvre bien les questions courantes
  Je garde aussi un bon souvenir du moment où mon premier conflit de merge m’a fait peur au point que j’ai arrêté, puis où j’ai contourné les choses pour éviter les conflits

  • git switch est une commande assez récente, publiée pour la première fois en 2019
    Il y a eu une discussion en 2021 et une autre il y a quelques semaines ; dans cette dernière, il est aussi indiqué que, dans la documentation, git switch est encore considéré comme une fonctionnalité expérimentale
    https://news.ycombinator.com/item?id=28024972
    https://news.ycombinator.com/item?id=42649858
  • Je ne dirais pas que git checkout est déjà considéré comme une « vieille alternative ». La dernière fois que j’ai vérifié, switch était toujours expérimental, et je n’ai jamais envisagé de m’éloigner du workflow et des commandes que j’ai appris il y a environ 15 ans avec Git
    Tout ce que je veux faire fonctionne toujours de la même façon, git checkout fait encore ce qu’il faisait avant, et je n’ai aucun problème à collaborer avec d’autres personnes via Git ; je ne vois donc pas pourquoi je changerais de workflow

• Le simple fait qu’il faille un guide en plus de 30 parties pour expliquer comment utiliser Git donne l’impression que Git est passé à côté de la vue d’ensemble

  • Je ne comprends pas pourquoi les programmeurs se mettent dans une telle colère à l’idée qu’un outil complexe, qui fait des choses complexes sur des structures de données complexes, ait un certain degré de complexité
  • Si les gens consacraient ne serait-ce que la moitié de l’énergie qu’ils mettent à se plaindre de Git à apprendre Git, il n’y aurait probablement pas besoin de faire un guide en plus de 30 parties pour expliquer ce qu’on trouve dans les pages de manuel
    Un commit est un instantané d’un arbre, avec une liste d’ancêtres. En général un seul, mais pas toujours. Un tag est une étiquette immuable pour un commit, et une branche est une étiquette mutable pour un commit. L’index est une sorte de petit proto-commit en cours, qu’on remplit avec add avant de committer
    Voilà Git. Si vous voulez en savoir plus, ne lisez pas un guide : cherchez plutôt des choses comme « comment passer à un commit Git précis sans affecter l’arbre », « comment committer seulement une partie des fichiers modifiés », ou « comment copier dans l’arbre courant un commit venu d’ailleurs »
    Les abstractions de base sont minimalistes et simples. Ce que vous voulez faire avec ces abstractions est sophistiqué et complexe. Apprenez les premières et cherchez les secondes, il n’est pas nécessaire de lire un guide
  • L’utilisation de Git peut même s’expliquer en 5 lignes de commentaire HN : git clone, git checkout, git pull, git add + commit + push, git reset / rebase
  • Et pourtant on peut quand même se tirer une balle dans le pied
  • Oui et non. Les commandes destinées aux utilisateurs de Git sont probablement assez bonnes pour 95 % des utilisateurs
    rebase -i indique quelle commande fait quoi, et quelques paragraphes suffisent pour expliquer comment formater la sortie de git log selon ses préférences et compromis. On considère généralement que les commandes utilisateur incluent aussi des choses assez diverses comme git gc, git fsck ou git rev-parse
    Les commandes de bas niveau sont clairement plus obscures, et font en elles-mêmes beaucoup de choses qu’on ne peut pas toujours accomplir facilement avec les commandes utilisateur optimisées pour les cas d’usage courants
    En résumé, Git est gros, voire énorme, mais pour la plupart des développeurs, une grande partie de ce qu’il offre se trouve loin du chemin principal

• Ce qui fait peur, c’est la longueur du guide
  Je sais que les guides de Beej sont en général exhaustifs, mais je n’avais pas vraiment pris la mesure de l’immense quantité de subtilités de Git avant de voir ça
  Avec Jujutsu, ce serait probablement un guide beaucoup plus mince, ou au moins un guide où l’on pourrait apprendre plus facilement par découverte progressive

  • J’essaie de faire en sorte que la plupart de mes guides permettent d’arrêter la lecture quand on estime en avoir assez lu. Il n’est pas nécessaire de tout lire
    J’ai l’impression que ce guide ne couvre qu’environ 10 % de Git, mais j’espère qu’il couvre 90 % des usages courants
  • Ce guide est plutôt exhaustif ; à l’autre extrême, il existe une fiche d’une page qui contient 90 % des commandes Git dont vous aurez besoin à l’avenir : https://wizardzines.com/git-cheat-sheet.pdf
  • Ça ressemble à un signe que Git n’est pas l’outil adapté à la plupart des gens, mais qu’il s’est retrouvé figé comme standard

• Au travail, une ou deux fois par an, j’anime une introduction au modèle de données de Git de 2 heures
  On va réellement dans le répertoire .git, on décompresse les fichiers et je montre que tout n’est qu’une représentation en texte clair des structures de données de base. Voir le moment où les gens comprennent enfin dans leur tête est vraiment génial
  On partage aux nouveaux arrivants un document de recettes Git de base pour qu’ils puissent commencer à committer du code, mais la plupart se contentent de le suivre sans comprendre ce qui se passe
  En revanche, les personnes qui ont suivi le cours, même si elles ne connaissent pas toutes les commandes, ont une compréhension opérationnelle assez raisonnable de ce qui se passe réellement dans Git. Les commandes se cherchent facilement ; si le modèle mental est correct, les commandes elles-mêmes ne sont pas un gros problème. Pourtant, presque toutes les discussions sur Git dans HN finissent par parler de ligne de commande
  Fait intéressant, ce cours ressemble au texte alternatif de https://xkcd.com/1597/. La différence, c’est que pour un public technique, c’est effectivement la bonne manière d’enseigner Git, et qu’une fois qu’on l’a compris, on acquiert une compréhension de base qu’on n’oublie pas
  Honnêtement, le retour sur investissement en temps est tellement élevé que je trouve étrange de ne pas le faire

  • Je l’ai fait une fois aussi, c’était vraiment bien, et la discussion qui a suivi était excellente
    Dans la dernière diapositive de la présentation, j’avais mis des questions auxquelles mes collègues devaient répondre à partir du modèle de données de Git. Par exemple : « peut-on déplacer un commit vers une autre branche ? », « qu’est-ce qui garantit qu’il n’y a pas de cycle dans le graphe des commits ? »
    C’était vraiment satisfaisant de voir les gens ne pas se contenter d’utiliser Git, mais penser Git
  • La phrase « si le modèle mental est correct, les commandes ne sont pas un gros problème » m’aurait d’abord fait penser à ce raisonnement qu’on voyait souvent dans les années 90 : « si l’on comprend toutes les couches et toutes les parties de Linux, alors utiliser Linux est facile ». Théoriquement vrai, mais irréaliste pour la plupart des gens
    Heureusement, j’ai vu assez tôt une vidéo qui expliquait une partie du modèle interne de Git, et j’ai constaté qu’en réalité il n’est pas nécessaire d’avoir des connaissances internes si nombreuses ou si profondes pour que cela fasse une grande différence. Comprendre ne serait-ce qu’environ 5 % du fonctionnement de Git m’a permis de bien mieux comprendre ce que font les commandes et comment les utiliser
  • Je me demande si vous pourriez partager les supports ou l’enregistrement de ce cours de 2 heures, s’il n’y a pas d’informations propriétaires ou de contraintes qui l’empêchent
    S’il était basé sur des ressources publiques et suffisamment concises pour tenir en 2 heures, ce serait bien de les partager dans ce fil ou dans l’article HN. Je pense que plus il existe de supports d’apprentissage sur un même sujet avec des présupposés, des analogies et des angles différents, mieux c’est
  • Je me demande s’il existe une copie de la présentation ou une vidéo, ou sinon des ressources similaires que vous recommanderiez
  • Partagez la vidéo, s’il vous plaît

• Je sais à peu près gérer le flux courant de Git, les merges, les rebases, etc., mais plutôt que d’essayer de devenir meilleur avec Git, j’envisage sérieusement de passer à jujutsu. jj est compatible avec Git, et je peux l’utiliser de mon côté pendant que mes collègues continuent simplement à utiliser Git

• J’ai l’impression qu’il y a une astuce que beaucoup de guides et la plupart des interfaces graphiques Git passent à côté. À titre d’exception, magit la traite bien
  Il s’agit de définir la branche upstream non pas sur origin/feature/foo pour feature/foo, mais sur la cible vers laquelle on veut fusionner, c’est-à-dire la branche d’intégration master ou origin/master
  Cela simplifie beaucoup de choses. Quand on lance git status, il indique à quel point on a divergé de la branche d’intégration, ce qui est utile, et si l’on lance git rebase sans argument, on est directement rebasé au-dessus de l’upstream
  Avoir origin/feature/foo comme upstream est moins utile. Les développeurs « possèdent » en général aussi leur propre branche distante, donc savoir à quel point on a divergé de celle-ci n’a pas vraiment d’intérêt, et on n’a pas non plus de raison de vouloir se rebaser dessus
  Si l’on définit push.default sur "current", git push pousse aussi feature/foo vers origin/feature/foo comme attendu
  Je me demande pourquoi cette configuration n’est pas plus répandue

• La section sur la collaboration ne traite pas du tout des branches de fonctionnalité. Il me semble pourtant que c’est un mode de travail assez courant
  Ce serait utile de la comparer à la méthode du guide où « chacun utilise sa propre branche ». Par ailleurs, dans la section 17, il vaudrait la peine d’aborder la réutilisation d’une branche pour les pull requests GitHub par rapport à la création d’une nouvelle branche pour chaque PR

• Je n’ai pas encore vérifié l’article, mais il a l’air bon. Autre recommandation : le cours Git de boot.dev, enseigné par Primeagen
  Il est interactif et va assez loin, jusqu’à manipuler directement les fichiers dans le répertoire .git. Après l’avoir suivi, j’ai acquis un modèle mental complètement nouveau du fonctionnement de Git