Utilisation de Git sur GitHub Docs

Cet article décrit le processus de création d’une branche de rubrique pour le dépôt de documentation, de commit des modifications et d’envoi (push) de vos modifications au dépôt distant.

L’article suppose que vous avez déjà cloné le dépôt de documentation localement, et que vous apporterez des modifications sur votre ordinateur local au lieu de le faire sur GitHub ou dans un codespace. Pour plus d’informations, consultez « Clonage d’un dépôt ».

Configuration de votre branche de rubrique et modifications

Pour maintenir la synchronisation de vos branches locales avec leurs versions distantes et éviter les conflits de fusion, procédez comme suit quand vous travaillez sur la documentation.

1. Dans le terminal, changez le répertoire de travail actuel pour l’emplacement où vous avez cloné le dépôt de documentation. Par exemple :

   cd ~/my-cloned-repos/docs
   

2. Passez à la branche par défaut : main.

   git checkout main
   

3. Obtenez les commits les plus récents auprès du dépôt distant.

   git pull origin main
   

4. Passez à une branche de rubrique ou créez-la.

   • Pour démarrer un nouveau projet, créez une branche de rubrique à partir de main.

     git checkout -b YOUR-TOPIC-BRANCH
     

     Remarque

     Vous pouvez utiliser des barres obliques dans le nom de la branche, par exemple pour inclure votre nom d’utilisateur :

     git checkout -b my-username/new-codespace-policy
     

   • Pour travailler sur un projet existant, basculez vers votre branche de rubrique et fusionnez les modifications à partir de main.

     git checkout YOUR-TOPIC-BRANCH
     git merge main
     

     Si vous rencontrez des conflits de fusion, suivez les étapes décrites plus loin dans cet article pour résoudre les conflits de fusion.

5. Ouvrez votre éditeur de texte préféré, modifiez les fichiers selon les besoins, puis enregistrez vos modifications.

Validation (commit) et envoi (push) de vos modifications

1. Quand vous êtes prêt à commiter vos modifications, ouvrez un terminal et vérifiez l’état de votre branche de rubrique avec git status. Vérifiez que vous voyez l’ensemble correct des modifications.

   git status
   On branch YOUR-TOPIC-BRANCH
   
   Changes not staged for commit:
     (use "git add <file>..." to update what will be committed)
     (use "git checkout -- <file>..." to discard changes in working directory)
           deleted:    example-deleted-file.md
           modified:   example-changed-file.md
   
   Untracked files:
     (use "git add <file>..." to include in what will be committed)
           example-new-file.md
   

2. Indexez les fichiers modifiés afin qu’ils soient prêts à être commités dans votre branche de rubrique.

   • Si vous avez créé de nouveaux fichiers ou mis à jour des fichiers existants, utilisez git add FILENAME [FILENAME...]. Par exemple :

     git add example-new-file.md example-changed-file.md
     

     Ceci ajoute la version mise à jour des fichiers à la zone de mise en place de Git, à partir de laquelle les modifications peuvent être commitées. Pour désindexer un fichier, utilisez git reset HEAD FILENAME. Par exemple : git reset HEAD example-changed-file.md.

   • Si vous avez supprimé des fichiers, utilisez git rm FILENAME [FILENAME...]. Par exemple :

     git rm example-deleted-file.md
     

3. Commitez vos changements.

   git commit -m "Commit message title (max 72 characters)
   
   Optional fuller description of what changed (no character limit).
   Note the empty line between the title and the description,
   and the closing quotation mark at the end of the commit message."
   

   Ceci commite les modifications indexées localement. Vous pouvez maintenant envoyer (push) ce commit et tous les autres commits non envoyés vers le dépôt distant.

   Pour supprimer ce commit, utilisez git reset --soft HEAD~1. Après l’exécution de cette commande, nos modifications ne sont plus commitées, mais les fichiers modifiés restent dans la zone d’indexation. Vous pouvez apporter d’autres modifications, puis effectuer à nouveau les opérations add et commit.

4. Envoyez vos modifications au dépôt distant sur GitHub.

   • La première fois que vous envoyez votre branche, vous pouvez choisir d’ajouter une branche de suivi amont. Ceci vous permet d’utiliser git pull et git push sur cette branche sans arguments supplémentaires.

     git push --set-upstream origin YOUR-TOPIC-BRANCH
     

   • Si vous avez déjà envoyé cette branche auparavant et que vous avez défini une branche de suivi amont, vous pouvez utiliser :

     git push
     

Bonnes pratiques pour les commits

• Privilégiez les commits qui contiennent de petits groupes de modifications ciblées par rapport aux commits avec des groupes de modifications en grande quantités et non ciblées, car cela vous aide à écrire des messages de commit que d’autres personnes peuvent alors facilement comprendre. L’exception à cette pratique est le commit initial pour un nouveau projet ou une nouvelle catégorie. Ces commits sont parfois de grande taille, car ils introduisent souvent les versions créées à partir de rien pour de nombreux articles à la fois, de façon à fournir un schéma organisationnel pour le travail ultérieur.

• Si vous incorporez du feedback ou que vous voulez destiner un ensemble de modifications à une personne ou une équipe particulière pour révision, utilisez @mention pour indiquer la personne dont vous incorporez les suggestions. Par exemple : « Incorporation du feedback de @octocat » ou « Mise à jour de l’exactitude des étapes de configuration de la facturation - cc @monalisa ».

• Si un commit résout un problème, vous pouvez référencer le numéro du problème dans le commit : un lien vers le commit va alors s’afficher dans la chronologie de la conversation sur le problème : « Résout #1234 - ajoute des étapes pour la sauvegarde de la machine virtuelle avant la mise à niveau ».

  Remarque

  En règle générale, nous ne fermons pas un problème via un commit. Pour fermer un problème, ouvrez une demande de tirage et ajoutez « Ferme #1234 » à la description. Le problème lié est fermé quand la demande de tirage est fusionnée. Pour plus d’informations, consultez « Relier une demande de tirage à un problème ».

• Rédigez des messages clairs, détaillés et impératifs pour les commits. Par exemple : « Ajouter un article conceptuel sur l’authentification à deux facteur », et non pas « Ajouter des informations ».

• Essayez de ne pas laisser des modifications non commitées dans votre branche locale quand vous arrêtez de travailler pour la journée. Déterminez un bon point d’arrêt, et commitez et envoyez vos modifications afin que votre travail soit sauvegardé dans le dépôt distant.

• Envoyez sur GitHub seulement après avoir effectué quelques commits. Envoyer après chaque commit ajoute du bruit à nos canaux d’opérations sur Slack et provoque l’exécution de builds inutiles.

Résolution des conflits de fusion

Quand vous tentez de fusionner deux branches qui contiennent des modifications différentes apportées à la même partie d’un fichier, vous rencontrez un conflit de fusion. Dans notre workflow, cela se produit le plus souvent lors de la fusion de main dans une branche de rubrique locale.

Il existe deux façons de gérer les conflits de fusion :

• Modifiez le fichier dans votre éditeur de texte et choisissez les modifications à conserver. Commitez ensuite le fichier mis à jour dans votre branche de rubrique à partir de la ligne de commande.
• Résolution d’un conflit de fusion sur GitHub.

Résoudre les conflits de fusion en modifiant le fichier et en commitant les modifications

1. Sur la ligne de commande, prenez note des fichiers qui contiennent des conflits de fusion.

2. Ouvrez le premier de ces fichiers dans votre éditeur de texte.

3. Dans le fichier, recherchez les marqueurs de conflit de fusion.

    <<<<<<< HEAD
    Here are the changes you've made.
    =====================
    Here are the changes from the main branch.
    >>>>>>> main
   

4. Décidez des modifications à conserver, et supprimez les modifications non souhaitées et les marqueurs de conflit de fusion. Si vous devez apporter d’autres modifications, vous pouvez le faire en même temps. Par exemple, vous pouvez remplacer les cinq lignes indiquées dans l’exemple de code précédent par une seule ligne :

   Here are the changes you want to use.
   

   S’il existe plusieurs fichiers avec des conflits de fusion, répétez les étapes précédentes jusqu’à avoir résolu tous les conflits.

   Remarque

   Vous devez faire attention lors de la résolution des conflits de fusion. Vous allez parfois simplement accepter vos propres modifications, parfois utiliser les modifications amont de la branche main, et parfois combiner les deux ensembles de modifications. Si vous n’êtes pas sûr de la meilleure résolution, faites attention si vous remplacez des modifications de l’amont, car elles peuvent avoir été apportées pour des raisons spécifiques dont vous n’avez pas connaissance.

5. Dans le terminal, indexez le ou les fichiers que vous venez de modifier.

   git add changed-file-1.md changed-file-2.md
   

6. Commitez les fichiers.

   git commit -m "Resolves merge conflicts"
   

7. Envoyez les modifications commitées au dépôt distant sur GitHub.

   git push
   

Création d’une demande de tirage

Nous vous recommandons d’ouvrir auparavant votre demande de tirage sur GitHub. Créez la demande de tirage en tant que brouillon jusqu’à ce que vous soyez prêt à ce qu’elle soit révisée. Chaque fois que vous envoyez des modifications, vos commits sont ajoutés à la demande de tirage.

Pour plus d’informations, consultez « Création d’une demande de tirage ».