Notions essentielles de Git pour l’éditeur

Comprenez les concepts de contrôle de version Git qui sous-tendent l’éditeur Mintlify, notamment les branches, les commits, les pull requests et les workflows de fusion.

Git vous permet de contrôler et de suivre les modifications apportées aux fichiers. Git est le système de contrôle de version de référence pour les workflows docs-as-code, où vous gérez la documentation comme n’importe quel autre code.

L’éditeur en ligne gère les opérations Git à votre place. Comprendre quelques concepts clés vous aide à tirer le meilleur parti de l’éditeur et à collaborer efficacement avec votre équipe.

Ce que Git fait pour votre documentation

Git suit chaque modification apportée à votre documentation. Il enregistre ce qui a changé, qui l’a modifié, quand cela a été modifié et pourquoi. Cela vous permet de :

• Voir l’historique complet de n’importe quelle page.
• Annuler des modifications en revenant à une version précédente.
• Travailler sur des mises à jour sans affecter votre site en ligne.
• Examiner les modifications avant leur mise en ligne.

Votre référentiel de documentation est l’ensemble des fichiers — et de leur historique — qui composent votre site de documentation. L’éditeur web se connecte à ce référentiel pour synchroniser et publier votre contenu.

Concepts clés

Voici les concepts Git que vous rencontrerez le plus souvent en utilisant l’éditeur web.

Commit

Une capture enregistrée de vos modifications à un moment précis. Chaque commit inclut un message décrivant ce qui a changé et crée un enregistrement permanent dans l’historique de votre projet.

Lorsque vous publiez des modifications, l’éditeur web crée un commit dans votre référentiel Git.

Branche

Une ligne de développement distincte dans votre référentiel. Parfois appelée feature branch.

Votre documentation en production est générée à partir d’une branche de déploiement, généralement appelée main. Les autres branches vous permettent de travailler sur des modifications de manière indépendante, sans affecter votre site en production. Rien sur une branche n’est mis en ligne avant que vous ne la fusionniez dans votre branche de déploiement au moyen d’une pull request.

Basculez entre les branches à l’aide de la liste déroulante des branches dans la barre d’outils de l’éditeur. Si vous avez des modifications non publiées, l’éditeur vous permet de les transférer vers la nouvelle branche ou de les laisser sur votre branche actuelle.

Branche de déploiement

La branche qui génère votre site de documentation en production, généralement appelée main. Les modifications fusionnées dans cette branche sont automatiquement déployées sur votre site.

Pull request

Une proposition visant à fusionner des modifications d’une branche dans une autre. Les pull requests permettent à votre équipe d’examiner et de discuter les changements avant leur mise en production.

Lorsque vous publiez des modifications sur une feature branch (ou lorsque votre référentiel exige des pull requests), l’éditeur web crée une pull request. Votre équipe examine et fusionne la pull request dans votre fournisseur Git (GitHub ou GitLab).

Fusion

L’action consistant à combiner les modifications d’une branche dans une autre. Une fois qu’une pull request a été examinée et approuvée par votre équipe, la fusion de la branche intègre vos modifications dans la branche de déploiement et les publie.

Conflit

Se produit lorsque deux branches comportent des modifications incompatibles sur les mêmes fichiers. L’éditeur vous aide à résoudre les conflits lorsqu’ils surviennent.

Diff

Une comparaison qui montre les différences entre deux versions d’un fichier. L’éditeur affiche un diff visuel de vos modifications en attente avant la publication, afin que vous puissiez vérifier exactement ce qui sera enregistré.

Correspondance entre l’éditeur et Git

Chaque action de publication dans l’éditeur web correspond à une opération Git.

Votre action dans l’éditeur	Opération Git en arrière-plan
Modifier une page	Les modifications sont enregistrées automatiquement sur les serveurs Mintlify (pas encore de commit Git)
Changer de branche	Faire un checkout de la branche sélectionnée
Publier sur votre branche de déploiement	Valider les modifications dans votre référentiel et déclencher un déploiement
Publier sur une feature branch	Valider les modifications et créer une pull request
Push externe ou mise à jour via la CLI	Les modifications entrantes sont synchronisées automatiquement dans l’éditeur