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:

• Determinare il repository appropriato.
• Creare una fork del repository nell'account GitHub.
• Scegliere una cartella locale per i file clonati.
• Clonare il repository nel computer locale.
• Configurare il valore remoto upstream.

Importante

Se si apportano solo modifiche secondarie, non è necessario completare i passaggi descritti in questo articolo. Per informazioni su come apportare modifiche rapide senza installare strumenti, vedere Modifica nel browser .

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.

Il repository Microsoft viene definito repository upstream. Usando l'azione fork all'interno dell'interfaccia utente di GitHub, l'utente inserisce il repository Microsoft nel proprio account GitHub. Questo fork viene definito origine. Usando git clone, l'utente clona l'origine nel computer locale. Infine, l'utente usa git remote add upstream per connettere il clone locale al repository upstream Microsoft.

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.

Avviso

1. NON clonare i repository locali in cartelle sincronizzate con OneDrive. Quando si sceglie la cartella in cui clonare il repository, evitare cartelle sincronizzate con OneDrive, ad esempio la cartella Documenti . OneDrive può causare conflitti di unione imprevisti quando si uniscono le modifiche al ramo principale. È invece consigliabile creare un percorso file breve nell'unità C:\ , ad esempio C:\GitHub.

2. Git in Windows: abilitare i nomi di percorso lunghi. Per impostazione predefinita, Git per Windows disabilita il supporto per percorsi file lunghi, che impedisce la clonazione di qualsiasi file con un percorso di destinazione superiore a 255 caratteri. Abilitare percorsi file lunghi per evitare questo problema eseguendo il comando seguente come amministratore:
   git config --global core.longpaths true

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 .

   

Importante

L'URL clone è stato copiato tramite l'interfaccia utente di GitHub. Il resto dei passaggi deve essere eseguito nel terminale di VS Code.

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.