Configurer un dépôt Git local pour la documentation

Cet article décrit les étapes à suivre pour configurer un référentiel Git sur un ordinateur local, dans l’intention de contribuer à la documentation de Microsoft. Les contributeurs peuvent utiliser un référentiel cloné localement pour ajouter de nouveaux articles, apporter des modifications importantes à des articles existants ou modifier des illustrations.

Avant de commencer à apporter vos contributions, vous devrez suivre la procédure de configuration suivante :

Vue d’ensemble

Pour contribuer à la documentation sur Microsoft Learn, vous pouvez créer et modifier des fichiers Markdown localement en clonant le dépôt de documentation correspondant. Microsoft vous impose de dupliquer (fork) le dépôt adéquat dans votre propre compte GitHub, de façon à ce que vous disposiez des autorisations de lecture/écriture nécessaires pour stocker les modifications que vous proposez. Vous utiliserez ensuite des demandes de tirage (pull requests) pour fusionner les modifications dans le dépôt central partagé en lecture seule.

Déterminer le référentiel

La documentation hébergée sur Microsoft Learn est répartie sur plusieurs dépôts différents sur GitHub.

1. Si vous ne savez pas dans quel dépôt se trouve un article, accédez-y à l’aide de votre navigateur web. Sélectionnez le lien Modifier (icône en forme de crayon) en haut à droite de l’article.

   

2. Cette action vous redirige vers le fichier source sur GitHub. Le nom du dépôt est affiché dans le coin supérieur gauche de la page.

   

   Voici quelques dépôts courants qui sont ouverts aux contributions publiques :

   • Contenu de Microsoft Learn Community https://github.com/MicrosoftDocs/community-content/
   • Documentation Azure https://github.com/MicrosoftDocs/azure-docs
   • Documentation SQL Server https://github.com/MicrosoftDocs/sql-docs
   • Documentation Visual Studio https://github.com/MicrosoftDocs/visualstudio-docs
   • Documentation .NET https://github.com/dotnet/docs
   • Documentation du SDK Azure pour .NET https://github.com/azure/azure-docs-sdk-dotnet
   • Documentation ConfigMgr https://github.com/MicrosoftDocs/SCCMdocs

Dupliquer (fork) le référentiel

Une fois que vous avez identifié le dépôt approprié, l’étape suivante consiste à le dupliquer dans votre propre compte GitHub.

La duplication d’un dépôt permet d’en créer une copie dans votre compte GitHub. Vous devez disposer de votre propre copie, car tous les dépôts de documentation Microsoft disposent d’un accès en lecture seule uniquement. Votre copie vous donne l’accès en écriture dont vous avez besoin pour apporter vos modifications. Cette duplication vous permet d’ouvrir des demandes de tirage à partir de votre copie vers le dépôt de Microsoft.

1. Depuis la page GitHub du dépôt principal, sélectionnez le bouton Dupliquer (fork) dans le coin supérieur droit.

   

2. Sur l’écran Créer une duplication, vérifiez que le Propriétaire est défini sur votre nom d’utilisateur et que l’option Copier la branche primaire uniquement est activée.. Si vous le souhaitez, modifiez les champs Nom du dépôt et Description.

   

Cloner le dépôt

L’action Cloner permet de créer une copie d’un dépôt sur votre ordinateur local.

1. Créez un dossier GitHub sur votre ordinateur local. Par exemple, C:\GitHub. (Ne clonez pas le dépôt dans un dossier synchronisé avec OneDrive.)

2. Dans un navigateur, accédez à GitHub.com et connectez-vous.

3. En haut à droite, dans le menu déroulant de votre profil, sélectionnez Vos dépôts. La page des dépôts s’affiche avec une liste de ceux que vous avez dupliqués.

4. Sélectionnez le dépôt que vous voulez cloner. La page de votre duplication s’affiche.

   Assurez-vous que vous êtes sur la page du dépôt de votre duplication, et non sur la page du dépôt de production. Vous pouvez confirmer que le dépôt sur lequel vous vous trouvez est votre duplication en vérifiant l’URL : elle doit afficher votre nom d’utilisateur GitHub, et non l’organisation Microsoft (par exemple, https://github.com/nancydavolio/azure-docs et non https://github.com/MicrosoftDocs/azure-docs). Vous verrez également votre nom dans le coin supérieur gauche, ainsi qu’une note indiquant qu’il s’agit d’une duplication, suivie du nom du dépôt d’origine.

   

5. Sélectionnez l’onglet <> Code en haut de la page.

6. Sur le côté droit, dans le menu déroulant Code, copiez l’URL sous l’option HTTPS.

   

Clonage à partir de Visual Studio Code

1. Ouvrez Visual Studio Code.

2. Dans le menu de navigation supérieur, sélectionnez Affichage, Terminal. Le terminal apparaît en bas de l’écran de Visual Studio Code.

3. Dans la vue Terminal, exécutez la commande pour modifier le répertoire (cd) et indiquer le dossier GitHub que vous avez créé pour les dépôts sur votre lecteur à l’étape 1 de la section Cloner le dépôt.

   Exemple :

    cd C:\GitHub
   

   Si une erreur s’affiche, vous devrez peut-être modifier le répertoire un dossier à la fois.

4. Exécutez la commande suivante pour cloner le dépôt :

   git clone <paste the clone URL you copied via the GitHub UI>
   

   Par exemple :

   git clone https://github.com/nancydavolio/azure-docs.git
   

5. Lorsque le système vous invite à vous authentifier via le navigateur, sélectionnez l’option « Se connecter avec votre navigateur » et suivez le processus. Veillez à télécharger la dernière version de Git, qui prend en charge l’authentification via le navigateur. Si vous choisissez d’utiliser un jeton d’accès personnel GitHub, vous pouvez en générer un en suivant les instructions suivantes de cette page : Créer un jeton d’accès personnel.

   La commande de clonage télécharge les fichiers du dépôt depuis votre duplication vers le dossier que vous avez indiqué à l’étape 3. Un nouveau dossier est créé dans le dossier actif. Cette opération peut prendre quelques minutes en fonction de la taille du dépôt. Vous pouvez explorer le dossier pour voir la structure une fois l’opération terminée.

Configurer des dépôts distants

Après avoir cloné le dépôt, configurez une connexion distante en lecture seule au dépôt principal nommé upstream. Les dépôts distants sont également parfois appelés « remotes » (« distants » en anglais). L’origine correspond à votre duplication, tandis que le dépôt en amont (upstream) fait référence au dépôt de production. Git crée automatiquement le dépôt distant origin lorsque vous exécutez la commande clone. Utilisez l’URL upstream pour synchroniser votre dépôt local avec les derniers changements apportés par d’autres utilisateurs.

Exécutez les commandes suivantes dans Git Bash ou dans le terminal VS Code.

1. Modifiez le répertoire (cd) pour indiquer le dossier du dépôt créé par la commande clone. Par exemple :

   cd repo-name
   

2. Exécutez la commande suivante pour ajouter un dépôt distant appelé upstream qui pointe vers le dépôt de production. Par exemple, l’URL du dépôt upstream est https://github.com/MicrosoftDocs/azure-docs.git et non https://github.com/nancydavolio/azure-docs.git.

   git remote add upstream <the clone URL of the main repo>
   

   Par exemple :

   git remote add upstream https://github.com/MicrosoftDocs/azure-docs.git
   

3. Exécutez la commande suivante pour vous assurer que vos dépôts distants sont corrects :

   git remote -v
   

   Exemple de sortie :

   origin  https://github.com/nancydavolio/azure-docs.git (fetch)
   origin  https://github.com/nancydavolio/azure-docs.git (push)
   upstream        https://github.com/MicrosoftDocs/azure-docs.git (fetch)
   upstream        https://github.com/MicrosoftDocs/azure-docs.git (push)
   

4. Si vous avez fait une erreur, supprimez le dépôt distant et ajoutez-le à nouveau en suivant la même procédure. Pour supprimer upstream, exécutez la commande suivante :

   git remote remove upstream
   

Étapes suivantes

• Maintenant que vous avez configuré votre clone local, il est temps d’apporter des modifications majeures.