Configurare un repository Git locale per la documentazione

In questo articolo vengono descritti i passaggi per configurare un repository Git nel computer locale, allo scopo di contribuire alla documentazione Microsoft. I collaboratori possono usare un repository clonato in locale per aggiungere nuovi articoli, apportare modifiche di rilievo ad articoli esistenti o modificare la grafica.

Per iniziare a contribuire, si eseguiranno queste attività di configurazione monouso:

Panoramica

Per contribuire alla documentazione su Microsoft Learn, è possibile creare e modificare i file Markdown in locale clonando il repository di documentazione corrispondente. Microsoft richiede di creare un fork del repository appropriato nel proprio account GitHub in modo da disporre delle autorizzazioni di lettura/scrittura per archiviare le modifiche proposte. Si usano quindi le richieste pull per unire le modifiche nel repository condiviso centrale di sola lettura.

Determinare il repository

La documentazione ospitata in Microsoft Learn si trova in diversi repository in GitHub.

1. Se non si è certi del repository in cui risiede un articolo, visitare l'articolo usando il Web browser. Selezionare il collegamento Modifica (icona a forma di matita) nell'angolo superiore destro dell'articolo.

   

2. Questa azione consente di accedere al file di origine in GitHub. Il nome del repository viene visualizzato nell'angolo superiore sinistro della pagina.

   

   Ecco alcuni repository più diffusi disponibili per i contributi pubblici:

   • Contenuto della community di Microsoft Learn https://github.com/MicrosoftDocs/community-content/
   • Documentazione di Azure https://github.com/MicrosoftDocs/azure-docs
   • Documentazione di SQL Server https://github.com/MicrosoftDocs/sql-docs
   • Documentazione di Visual Studio https://github.com/MicrosoftDocs/visualstudio-docs
   • Documentazione di .NET https://github.com/dotnet/docs
   • Documentazione di Azure .NET SDK https://github.com/azure/azure-docs-sdk-dotnet
   • Documentazione di ConfigMgr https://github.com/MicrosoftDocs/SCCMdocs

Creare una copia tramite fork del repository

Dopo aver identificato il repository corretto, il passaggio successivo consiste nel creare un fork del repository nel proprio account GitHub.

Per creare una copia tramite fork di un repository, è necessario crearne una copia nell'account GitHub. È necessario un fork personale perché tutti i repository di documentazione Microsoft forniscono l'accesso in sola lettura, ma il fork consente di accedere in scrittura per apportare le modifiche. Il fork consente di aprire le richieste pull dal fork al repository Microsoft.

1. Nella pagina GitHub del repository principale selezionare il pulsante Fork nell'angolo in alto a destra.

   

2. Nella schermata Crea una nuova fork verificare che Proprietario sia impostato sul nome utente e che l'opzione Copia il ramo principale sia selezionata solo. Facoltativamente, modificare i campi Nome repository e Descrizione .

   

Clonare il repository

Clone significa creare una copia di un repository nel computer locale.

1. Creare una GitHub cartella nel computer locale. Ad esempio, C:\GitHub. Non clonare in una cartella sincronizzazione OneDrive ed.

2. In un browser passare a GitHub.com ed eseguire l'accesso.

3. In GitHub in alto a destra, nell'elenco a discesa del profilo selezionare Repository. La pagina dei repository viene visualizzata con un elenco dei repository con fork.

4. Selezionare il repository da clonare. Verrà visualizzata la pagina del repository del fork.

   Assicurarsi di essere nella pagina del repository per il fork, non della pagina per il repository di produzione. È possibile verificare che il repository in uso sia il fork controllando l'URL: dovrebbe visualizzare il nome utente gitHub, non l'organizzazione Microsoft ( ad esempio https://github.com/nancydavolio/azure-docs e NOT https://github.com/MicrosoftDocs/azure-docs). Verrà anche visualizzato il nome nell'angolo in alto a sinistra e verrà visualizzata una nota che indica la copia tramite fork seguita dal nome del repository principale.

   

5. Selezionare la <> scheda Codice in alto a sinistra della pagina.

6. Sul lato destro, nell'elenco a discesa Codice copiare l'URL sotto l'opzione HTTPS .

   

Per clonare da Visual Studio Code

1. Aprire Visual Studio Code.

2. Dal menu di spostamento in alto selezionare Visualizza e quindi terminale. La visualizzazione del terminale viene visualizzata nella parte inferiore della schermata di Visual Studio Code.

3. Nella visualizzazione Terminale eseguire il comando per modificare la directory (cd) nella GitHub cartella creata per i repository nell'unità nel passaggio 1 della sezione Clonare un repository.

   Esempio:

    cd C:\GitHub
   

   Se viene visualizzato un errore, potrebbe essere necessario modificare la directory una alla volta.

4. Eseguire il comando seguente per clonare il repository:

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

   Ad esempio:

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

5. Quando viene richiesto di eseguire l'autenticazione tramite il browser, scegliere il pulsante "Accedi con il browser" e completare il processo. Assicurarsi di scaricare la versione più recente di Git, che supporta l'autenticazione tramite la funzionalità del browser. Se si sceglie di usare un token di accesso personale GitHub, è possibile generare una delle istruzioni seguenti: Creare un token di accesso personale.

   Il comando clone scarica i file del repository dal fork in una nuova cartella nel percorso scelto nel passaggio 3. Viene creata una nuova cartella all'interno della cartella corrente. Possono essere necessari alcuni minuti, in base alla dimensione del repository. È possibile esplorare la cartella per visualizzare la struttura al termine dell'operazione.

Configurare i remote

Dopo aver clonato il repository, impostare una connessione remota di sola lettura al repository principale denominata upstream. I remote sono alias che fanno riferimento a repository remoti. L'origine fa riferimento al fork e upstream fa riferimento al repository di produzione. Git ha creato automaticamente il origin telecomando quando è stato eseguito il clone comando. L'URL di upstream verrà usata per mantenere il repository locale sincronizzato con le modifiche più recenti apportate da altri.

Eseguire i comandi seguenti nel terminale Git Bash o VS Code.

1. Modificare la directory (cd) nella cartella del repository creata dal clone comando. Ad esempio:

   cd repo-name
   

2. Eseguire il comando seguente per aggiungere un oggetto remoto denominato upstream che punta al repository di produzione. Ad esempio, l'URL del upstream repository è https://github.com/MicrosoftDocs/azure-docs.git anziché https://github.com/nancydavolio/azure-docs.git.

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

   Ad esempio:

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

3. Eseguire il comando seguente per assicurarsi che i remote siano corretti:

   git remote -v
   

   Esempio di output:

   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. Se si è commesso un errore, rimuovere il telecomando e ripetere il passaggio per aggiungerlo. Per rimuovere upstream, eseguire il comando :

   git remote remove upstream
   

Passaggi successivi

• Dopo aver configurato il clone locale, è possibile apportare modifiche importanti.