Configurar um repositório Git local para documentação

Este artigo descreve os passos para configurar um repositório Git no computador local, com o objetivo de contribuir para a documentação da Microsoft. Os contribuintes podem utilizar um repositório clonado localmente para adicionar artigos novos, fazer grandes edições em artigos existentes ou alterar os elementos artísticos.

Você executará estas atividades de configuração única para começar a contribuir:

• Determine o repositório apropriado.
• Fork o repositório para sua conta GitHub.
• Escolha uma pasta local para os arquivos clonados.
• Clone o repositório para o seu computador local.
• Configure o valor remoto upstream.

Importante

Se você estiver fazendo apenas pequenas alterações, não precisará concluir as etapas neste artigo. Consulte Editar no navegador para saber como fazer edições rápidas sem instalar ferramentas.

Descrição geral

Para contribuir com a documentação do Microsoft Learn, você pode criar e editar arquivos Markdown localmente clonando o repositório de documentação correspondente. A Microsoft exige que você bifurque o repositório apropriado em sua própria conta do GitHub para que você tenha permissões de leitura/gravação para armazenar as alterações propostas. Em seguida, use solicitações pull (PRs) para mesclar alterações no repositório compartilhado central somente leitura.

O repositório da Microsoft é conhecido como o repositório upstream. Usando a ação de bifurcação na interface do usuário do GitHub, o usuário bifurca o repositório da Microsoft em sua própria conta do GitHub. Esta bifurcação é referida como a Origem. Usando o git clone, o usuário clona o Origin para sua máquina local. Finalmente, o usuário usa o git remote add upstream para conectar seu clone local de volta ao repositório upstream da Microsoft.

Determinar o repositório

A documentação hospedada no Microsoft Learn reside em vários repositórios no GitHub.

1. Se você não tiver certeza de em qual repositório um artigo reside, visite o artigo usando seu navegador da Web. Selecione o link Editar (ícone de lápis) no canto superior direito do artigo.

   

2. Esta ação leva você ao arquivo de origem no GitHub. O nome do repositório é exibido no canto superior esquerdo da página.

   

   Aqui estão alguns repositórios populares que estão disponíveis para contribuições públicas:

   • Conteúdo da comunidade do Microsoft Learn https://github.com/MicrosoftDocs/community-content/
   • Documentação do Azure https://github.com/MicrosoftDocs/azure-docs
   • Documentação do SQL Server https://github.com/MicrosoftDocs/sql-docs
   • Documentação do Visual Studio https://github.com/MicrosoftDocs/visualstudio-docs
   • Documentação do .NET https://github.com/dotnet/docs
   • Documentação do SDK do Azure .NET https://github.com/azure/azure-docs-sdk-dotnet
   • Documentação do ConfigMgr https://github.com/MicrosoftDocs/SCCMdocs

Bifurcar o repositório

Depois de identificar o repositório correto, a próxima etapa é bifurcar o repositório em sua própria conta do GitHub.

Fork um repositório significa criar uma cópia dele em sua conta do GitHub. Uma bifurcação pessoal é necessária porque todos os repositórios de documentação da Microsoft fornecem acesso somente leitura, mas sua bifurcação lhe dá acesso de gravação para fazer suas alterações. A bifurcação permite que você abra PRs da sua bifurcação para o repositório da Microsoft.

1. Na página GitHub do repositório principal, selecione o botão Fork no canto superior direito.

   

2. Na tela Criar uma nova bifurcação, verifique se Proprietário está definido como seu nome de usuário e se a opção Copiar somente a ramificação principal está marcada. Opcionalmente, altere os campos Nome do repositório e Descrição.

   

Clonar o repositório

Clone significa criar uma cópia de um repositório em sua máquina local.

Aviso

1. NÃO clone repositórios locais em pastas sincronizadas com o OneDrive. Ao escolher a pasta na qual você clonará o repositório, evite pastas sincronizadas com o OneDrive (por exemplo, sua pasta Documentos ). O OneDrive pode causar conflitos de mesclagem não intencionais quando você mescla suas alterações de volta à ramificação principal. Em vez disso, é melhor criar um caminho de arquivo curto em sua C:\ unidade (por exemplo, C:\GitHub).

2. Git no Windows: habilite nomes de caminhos longos. Por padrão, o Git para Windows desabilita o suporte para caminhos de arquivos longos, o que impede que qualquer arquivo com um caminho de destino com mais de 255 caracteres seja clonado. Habilite caminhos de arquivo longos para evitar esse problema executando o seguinte comando como administrador:
   git config --global core.longpaths true

1. Crie uma GitHub pasta na sua máquina local. Por exemplo, C:\GitHub. (Não clone para uma pasta sincronizada do OneDrive.)

2. Num browser, aceda a GitHub.com e inicie sessão.

3. No GitHub, no canto superior direito, na lista suspensa do seu perfil, selecione Seus repositórios. A página de repositórios aparece com uma lista dos repositórios bifurcados.

4. Selecione o repositório que deseja clonar. A página do repositório de Sua bifurcação é exibida.

   Certifique-se de que você está na página do repositório para sua bifurcação , não na página para o repositório de produção. Você pode confirmar que o repositório em que você está é sua bifurcação verificando a URL: ela deve mostrar seu nome de usuário do GitHub, não a organização da Microsoft (por exemplo, https://github.com/nancydavolio/azure-docs e NÃO https://github.com/MicrosoftDocs/azure-docs). Além disso, você verá seu nome no canto superior esquerdo e verá uma nota que diz bifurcada seguida pelo nome do repositório principal.

   

5. Selecione a <> guia Código no canto superior esquerdo da página.

6. No lado direito, na lista suspensa Código, copie o URL na opção HTTPS.

   

Importante

Você copiou a URL de clone por meio da interface do usuário do GitHub. As restantes etapas devem ser executadas no VS Code Terminal.

Para clonar do Visual Studio Code

1. Abra o Visual Studio Code.

2. No menu de navegação superior, selecione Ver e, em seguida, selecione Terminal. O modo de exibição de terminal aparece na parte inferior da tela de código do Visual Studio.

3. Na visualização Terminal, execute o comando para alterar o diretório (cd) para a GitHub pasta que você criou para repositórios em sua unidade na Etapa 1 na seção Clonar um repositório.

   Exemplo:

    cd C:\GitHub
   

   Se você receber um erro, talvez seja necessário alterar o diretório uma pasta de cada vez.

4. Execute o seguinte comando para clonar o repositório:

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

   Por exemplo:

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

5. Quando solicitado a autenticar através do navegador, escolha o botão "Entrar com seu navegador" e conclua o processo. Certifique-se de baixar a versão mais recente do Git, que suporta autenticação via funcionalidade do navegador. Se você optar por usar um token de acesso pessoal do GitHub, poderá gerar um seguindo estas instruções: Criar um token de acesso pessoal.

   O comando clone baixa os arquivos do repositório da bifurcação para uma nova pasta no local escolhido na Etapa 3. É criada uma nova pasta dentro da pasta local. Este processo poderá demorar alguns minutos, consoante o tamanho do repositório. Você pode explorar a pasta para ver a estrutura assim que ela estiver concluída.

Configurar controles remotos

Depois de clonar o repositório, configure uma ligação remota só de leitura, denominada upstream, para o repositório principal. Remotos são aliases que se referem a repositórios remotos. Origem refere-se à sua bifurcação e upstream refere-se ao repositório de produção. O Git criou automaticamente o origin controle remoto quando você executou o clone comando. Utilize o URL de origem para manter o repositório local sincronizado com as alterações mais recentes realizadas por terceiros.

Execute os seguintes comandos no Git Bash ou no VS Code Terminal.

1. Altere o diretório (cd) para a pasta do repositório que o clone comando criou. Por exemplo:

   cd repo-name
   

2. Execute o comando a seguir para adicionar um controle remoto nomeado upstream que aponte para o repositório de produção. Por exemplo, o URL do upstream repositório é https://github.com/MicrosoftDocs/azure-docs.git em vez de https://github.com/nancydavolio/azure-docs.git.

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

   Por exemplo:

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

3. Execute o seguinte comando para certificar-se de que os controles remotos estão corretos:

   git remote -v
   

   Exemplo de saída:

   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 você cometeu um erro, remova o controle remoto e repita a etapa para adicioná-lo. Para remover upstream, execute o comando:

   git remote remove upstream
   

Próximos passos

• Agora que você configurou seu clone local, é hora de fazer grandes alterações.