Configurar repositório Git local para documentação

Este artigo descreve as etapas para configurar um repositório GIT na sua máquina local, com a intenção de contribuir para a documentação da Microsoft. Colaboradores podem usar um repositório clonado localmente para adicionar novos artigos, fazer edições importantes em artigos existentes ou alterar a arte.

Execute estas atividades avulsas de configuração única para começar a contribuir:

Visão geral

Para contribuir com a documentação do Microsoft Learn, você pode criar e editar arquivos de Markdown localmente clonando o repositório de documentação correspondente. A Microsoft requer a criação de um fork do repositório apropriado na 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 pull requests (PRs) para mesclar as alterações no repositório compartilhado central de somente leitura.

Determinar o repositório

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

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

   

2. Essa 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 disponíveis para contribuições públicas:

   • Conteúdo da Microsoft Learn Community 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 para .Net https://github.com/azure/azure-docs-sdk-dotnet
   • Documentação do ConfigMgr https://github.com/MicrosoftDocs/SCCMdocs

Criar um fork do repositório

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

Criar fork de um repositório significa criar uma cópia dele na sua conta do GitHub. Um fork pessoal é necessário porque todos os repositórios de documentação da Microsoft fornecem acesso de somente leitura, mas seu fork fornece acesso para gravação que permite fazer as alterações. A bifurcação permite que você abra as PRs do seu fork no repositório da Microsoft.

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

   

2. Na tela Criar um fork, verifique se o 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

Clonar significa criar uma cópia de um repositório em seu computador local.

1. crie uma pasta GitHub no seu computador local. Por exemplo, C:\GitHub. (Não clone para uma pasta sincronizada do OneDrive.)

2. Em um browser, acesse GitHub.com e inicie uma 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 de seus repositórios bifurcados.

4. Selecione o repositório que deseja clonar. A página do repositório de Seu fork é exibida.

   Verifique se você está na página do repositório da sua bifurcação, , não na página do repositório de produção. Você pode confirmar que o repositório em que você está é seu fork 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 bifurcado de seguido pelo nome do repositório principal.

   

5. Selecione a guia <>Código na parte superior esquerda da página.

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

   

Para clonar por meio do Visual Studio Code

1. Abra o Visual Studio Code.

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

3. No modo de visualização de Terminal, execute o comando para alterar o diretório (cd) na pasta GitHub criada para repositórios na unidade durante a Etapa 1 da seção Clonar um repositório.

   Exemplo:

    cd C:\GitHub
   

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

4. Execute o comando a seguir 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 por meio do browser, escolha o botão "Iniciar sessão com seu browser" e conclua o processo. Certifique-se de baixar a última versão do Git, que suporta autenticação via funcionalidade do browser. 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 faz o download dos arquivos de repositório do seu fork para uma nova pasta no local escolhido na Etapa 3. Uma nova pasta é criada dentro da pasta atual. Isso pode levar alguns minutos dependendo do tamanho do repositório. É possível explorar a pasta para ver a estrutura após sua conclusão.

Configurar repositórios remotos

Após clonar o repositório, configure uma conexão remota somente leitura com o repositório principal nomeado upstream. Remotos são aliases que se referem a repositórios remotos. Origem refere-se ao seu fork, e upstream refere-se ao repositório de produção. O Git criou automaticamente o repositório remoto origin quando você executou o comando clone. Use a URL upstream para manter seu repositório local sincronizado com as últimas alterações feitas por outras pessoas.

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

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

   cd repo-name
   

2. Execute o comando a seguir para adicionar um repositório remoto nomeado upstream que aponte para o repositório de produção. Por exemplo, a URL do repositório do upstream é 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 verificar se os repositórios 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 repositório remoto e repita a etapa para adicioná-lo. Para remover upstream, execute o comando:

   git remote remove upstream
   

Próximas etapas

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