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 :

• Identifiez un dépôt adéquat.
• Dupliquez le dépôt sur votre compte GitHub.
• Choisissez un dossier local pour les fichiers clonés.
• Clonez le dépôt sur votre ordinateur local.
• Configurez la valeur à distance en amont.

Important

Si vous n’effectuez que des changements mineurs, vous n’avez pas besoin d’effectuer les étapes décrites dans cet article. Consultez la page portant sur la modification dans le navigateur pour savoir comment effectuer des modifications rapides sans installer d’outils.

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.

Le dépôt Microsoft d’origine est souvent appelé dépôt en amont. À l’aide de l’action de duplication (fork) dans l’interface utilisateur GitHub, l’utilisateur duplique le dépôt Microsoft dans son propre compte GitHub. Ce dépôt est appelé Origine. À l’aide de l’action git clone, l’utilisateur clone l’Origine sur son ordinateur local. Enfin, l’utilisateur utilise l’action git remote add upstream pour connecter son clone local au dépôt Microsoft en amont.

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.

Avertissement

1. Ne clonez PAS les dépôts dans des dossiers synchronisés avec OneDrive. Lorsque vous choisissez le dossier dans lequel vous clonez le dépôt, évitez ceux qui sont synchronisés avec OneDrive (par exemple, votre dossier Documents). OneDrive peut provoquer des conflits involontaires lorsque vous fusionnez vos modifications avec la branche primaire. Il est préférable de créer un chemin de fichier court sur votre lecteur C:\ (par exemple, C:\GitHub).

2. Git sur Windows : activer les noms de chemin d’accès longs. Par défaut, Git pour Windows désactive la prise en charge des chemins d’accès longs, ce qui empêche le clonage de tout fichier dont le chemin d’accès de destination dépasse 255 caractères. Pour éviter ce problème, activez les noms de chemin d’accès longs en exécutant la commande suivante en tant qu’administrateur :
   git config --global core.longpaths true

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.

   

Important

Vous avez copié l’URL du clone via l’interface utilisateur de GitHub. Le reste des étapes doit être effectué dans le Terminal de VS Code.

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.