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:

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

Importante

Se você estiver fazendo apenas alterações menores em um artigo, não é necessário concluir as etapas deste artigo. Confira Editar no browser para saber como fazer edições rápidas sem instalar nenhuma ferramenta.

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.

Screenshot showing the GitHub workflow for information flowing between the upstream, origin, and local clone.

O repositório da Microsoft geralmente é chamado de 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. Essa bifurcação é conhecida como a Origem. Usando o git clone, o usuário clona a Origem em seu computador local. Por fim, o usuário usa o git remote add upstream para conectar seu clone local novamente ao repositório upstream da Microsoft.

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.

    Screenshot of the pencil edit icon on a Microsoft documentation article.

  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.

    Screenshot of where the repo name is found in a GitHub repo.

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

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.

    Screenshot of the fork icon in the GitHub user interface.

  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.

    Screenshot of the Create a new fork screen.

Clonar o repositório

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

Aviso

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

  2. Windows do Git: habilitar nomes de caminho 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 arquivos longos para evitar esse issue executando o seguinte comando como administrador:
    git config --global core.longpaths true

  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 de seu fork, 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ÃOhttps://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.

    Screenshot showing a forked repo in GitHub.

  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.

    Screenshot showing how to copy the clone HTTPS URL in GitHub.

Importante

Você copiou a URL do clone por meio da interface do usuário do GitHub. O restante das etapas deve ser executado no VS Code Terminal.

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