# Usando o Git na Documentação do GitHub

Você pode usar o Git na linha de comando para commitar alterações e depois empurrá-las para o repositório de documentação.

Este artigo descreve o processo de criação de um branch do tópico no repositório da documentação, commit de alterações e push das alterações novamente para o repositório remoto.

O artigo pressupõe que você já clonou localmente o repositório de documentação e fará alterações no seu computador local, em vez de em GitHub ou em um codespace. Para saber mais, confira [Clonar um repositório](/pt/enterprise-server@3.22/repositories/creating-and-managing-repositories/cloning-a-repository?tool=webui).

## Como configurar o branch do tópico e fazer alterações

Para manter os branches locais sincronizados com os repositórios remotos e evitar conflitos de mesclagem, siga estas etapas enquanto trabalha na documentação.

1. No terminal, altere o diretório de trabalho atual para o local em que você clonou o repositório da documentação. Por exemplo:

   ```shell
   cd ~/my-cloned-repos/docs
   ```

2. Alterne para o branch padrão: `main`.

   ```shell
   git checkout main
   ```

3. Obtenha os commits mais recentes do repositório remoto.

   ```shell
   git pull origin main
   ```

4. Alterne para a ramificação do tópico ou crie um.
   * Para iniciar um novo projeto, crie um ramo de tópico a partir de `main`.

     ```shell
     git checkout -b YOUR-TOPIC-BRANCH
     ```

     > \[!NOTE]
     > Você pode usar barras como parte do nome da ramificação, por exemplo, para incluir seu nome de usuário:
     >
     > ```shell
     > git checkout -b my-username/new-codespace-policy
     > ```

   * Para trabalhar em um projeto existente, alterne para a ramificação do tópico e mescle as alterações de `main`.

     ```shell
     git checkout YOUR-TOPIC-BRANCH
     git merge main
     ```

     Caso encontre conflitos de mesclagem, siga as etapas descritas mais adiante neste artigo para [resolver conflitos de mesclagem](#resolving-merge-conflicts).

5. Abra seu editor de texto preferido, edite os arquivos conforme necessário e salve as alterações.

## Enviando e fazendo push das suas alterações

1. Quando estiver pronto para fazer commit das alterações, abra um terminal e verifique o status da ramificação do tópico com `git status`. Verifique se você está vendo o conjunto correto de alterações.

   ```shell
   git status
   On branch YOUR-TOPIC-BRANCH

   Changes not staged for commit:
     (use "git add <file>..." to update what will be committed)
     (use "git checkout -- <file>..." to discard changes in working directory)
           deleted:    example-deleted-file.md
           modified:   example-changed-file.md

   Untracked files:
     (use "git add <file>..." to include in what will be committed)
           example-new-file.md
   ```

2. Prepare os arquivos alterados para que eles fiquem prontos para serem confirmados na ramificação do tópico.

   * Se você criou arquivos ou atualizou arquivos existentes, use `git add FILENAME [FILENAME...]`. Por exemplo:

     ```shell
     git add example-new-file.md example-changed-file.md
     ```

     Isso adicionará a versão atualizada dos arquivos à área de preparo do Git, da qual as alterações podem ser confirmadas. Para cancelar o preparo de um arquivo, use `git reset HEAD FILENAME`. Por exemplo, `git reset HEAD example-changed-file.md`.

   * Se você excluiu arquivos, use `git rm FILENAME [FILENAME...]`. Por exemplo:

     ```shell
     git rm example-deleted-file.md
     ```

3. Fazer commit de suas alterações.

   ```shell
   git commit -m "Commit message title (max 72 characters)

   Optional fuller description of what changed (no character limit).
   Note the empty line between the title and the description,
   and the closing quotation mark at the end of the commit message."
   ```

   Isso fará o commit das alterações preparadas localmente. Agora você pode efetuar push desse commit e de todos os outros commits sem push para o repositório remoto.

   Para remover esse commit, use `git reset --soft HEAD~1`. Após a execução desse comando, as alterações não são mais confirmadas, mas os arquivos alterados permanecem na área de preparo. Você poderá fazer mais alterações e, em seguida, usar `add` e `commit` novamente.

4. Envie suas alterações para o repositório remoto em GitHub.

   * Na primeira vez que você efetua push do branch, você pode optar por adicionar um branch de acompanhamento de upstream. Isso permite que você use `git pull` e `git push` nesse ramo sem argumentos adicionais.

     ```shell
     git push --set-upstream origin YOUR-TOPIC-BRANCH
     ```

   * Se você já efetuou push desse branch antes e definiu um branch de acompanhamento de upstream, use:

     ```shell
     git push
     ```

### Melhores práticas de commits

* Dê preferência a commits que contêm grupos pequenos e concentrados de alterações em vez de commits com grupos grandes e desconcentrados de alterações, pois isso ajudará você a escrever mensagens de commit que outras pessoas possam entender com facilidade. Uma exceção é o commit inicial de um novo projeto ou de uma nova categoria. Às vezes, esses commits são grandes, pois, em geral, introduzem as versões básicas de muitos artigos ao mesmo tempo a fim de fornecer um esquema organizacional para os trabalhos seguintes.

* Se você estiver incorporando comentários ou quiser lidar com um conjunto de alterações em determinada pessoa ou equipe para revisão, @mention a pessoa cujas sugestões você está incorporando. Por exemplo: "Incorporação de comentários de @octocat" ou "Atualização das etapas de configuração de cobrança – CC @monalisa para precisão".

* Se um commit resolver um problema, você poderá referenciar o número do problema no commit e um link para o commit será exibido na linha do tempo da conversa do problema: "Resolve o nº 1234 – Adiciona etapas para fazer backup da VM antes da atualização".

  > \[!NOTE]
  > Em geral, não fechamos um problema por meio de um commit. Para fechar um problema, abra uma pull request e adicione "Fecha o nº 1234" à descrição. O problema vinculado será fechado quando a pull request for mesclada. Para saber mais, confira [Vinculando uma pull request a um problema](/pt/enterprise-server@3.22/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).

* Torne as mensagens de commit claras, detalhadas e imperativas. Por exemplo: "Adicionar um artigo conceitual sobre a 2FA", não "Adicionar informações".

* Tente não deixar alterações não confirmadas no branch local quando terminar de trabalhar no dia. Chegue a um bom ponto de parada e faça commit e efetue push das alterações para que o backup do trabalho seja feito no repositório remoto.

* Realize o push para GitHub somente após algumas confirmações. O push após cada commit adiciona ruído aos nossos canais de operações no Slack e faz com que builds desnecessários sejam executados.

## Resolução de conflitos de mesclagem

Ao tentar mesclar duas ramificações que contêm alterações diferentes na mesma parte de um arquivo, você encontrará um conflito de mesclagem. Em nosso fluxo de trabalho, isso costuma ocorrer ao mesclar o `main` em um branch do tópico local.

Há duas maneiras de resolver conflitos de mesclagem:

* Edite o arquivo no editor de texto e escolha as alterações que serão mantidas. Em seguida, faça commit do arquivo atualizado no branch do tópico por meio da linha de comando.
* [Resolvendo um conflito de mesclagem no GitHub](/pt/enterprise-server@3.22/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github).

### Como resolver os conflitos de mesclagem editando o arquivo e fazendo commit das alterações

1. Na linha de comando, observe os arquivos que contêm conflitos de mesclagem.

2. Abra o primeiro desses arquivos no editor de texto.

3. No arquivo, procure os marcadores de conflitos de mesclagem.

   ```text
    <<<<<<< HEAD
    Here are the changes you've made.
    =====================
    Here are the changes from the main branch.
    >>>>>>> main
   ```

4. Decida quais alterações serão mantidas e exclua as alterações indesejadas e os marcadores de conflitos de mesclagem. Caso precise fazer mais alterações, faça isso ao mesmo tempo. Por exemplo, você pode alterar as cinco linhas mostradas no exemplo de código anterior para a única linha:

   ```text
   Here are the changes you want to use.
   ```

   Se houver vários arquivos com conflitos de mesclagem, repita as etapas anteriores até resolver todos os conflitos.

   > \[!NOTE]
   > Você deve ter cuidado ao resolver conflitos de mesclagem. Às vezes, você apenas aceitará suas alterações, outras, usará as alterações upstream do branch `main` e, outras vezes, ainda, combinará os dois conjuntos de alterações. Se não tiver certeza da melhor resolução, tenha cuidado ao substituir as alterações upstream, pois elas podem ter sido feitas por razões específicas das quais você não esteja ciente.

5. No terminal, prepare os arquivos que acabou de modificar.

   ```shell
   git add changed-file-1.md changed-file-2.md
   ```

6. Faça commit deles.

   ```shell
   git commit -m "Resolves merge conflicts"
   ```

7. Envie por push as alterações confirmadas para o repositório remoto em GitHub.

   ```shell
   git push
   ```

## Como criar uma solicitação de pull

Recomendamos que você abra sua pull request em GitHub o quanto antes. Crie a pull request como um rascunho até estar pronto para que ela seja revisada. Sempre que você efetuar push das alterações, os commits serão adicionados à pull request.

> \[!NOTE]
> Você pode acessar rapidamente as pull requests que você criou clicando em **Pull requests** no topo de cada página em GitHub.

Para saber mais, confira [Como criar uma solicitação de pull](/pt/enterprise-server@3.22/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui#creating-the-pull-request).