Como usar o Git no GitHub Docs

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á tenha clonado o repositório da documentação localmente e fará alterações no computador local em vez de no GitHub.com ou em um codespace. Para obter mais informações, confira "Clonar um repositório".

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.

No terminal, altere o diretório de trabalho atual para o local em que você clonou o repositório da documentação. Por exemplo:
```
cd ~/my-cloned-repos/docs
```
Alterne para o branch padrão: main.
```
git checkout main
```
Obtenha os commits mais recentes do repositório remoto.
```
git pull origin main
```
Alterne para o branch do tópico ou crie um.
- Para iniciar um novo projeto, crie um branch do tópico com base no main.
```
git checkout -b YOUR-TOPIC-BRANCH
```
  Observação: você pode usar barras '/' como parte do nome do branch, por exemplo, para incluir seu nome de usuário:
```
git checkout -b my-username/new-codespace-policy
```
- Para trabalhar em um projeto existente, alterne para o branch do tópico e mescle as alterações de main.
```
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.
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

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

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

Prepare os arquivos alterados para que eles fiquem prontos para serem confirmados no branch do tópico.
- Se você criou arquivos ou atualizou arquivos existentes, use git add FILENAME [FILENAME...]. Por exemplo:
```
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:
```
git rm example-deleted-file.md
```
Fazer commit de suas alterações.
```
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.
Faça um push das alterações no repositório remoto do 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 branch sem argumentos adicionais.
```
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:
```
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".

Observação: 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 obter mais informações, confira "Vinculando uma pull request a um problema".
Torne as mensagens de commit claras, detalhadas e imperativas. Por exemplo: "Adiciona um artigo conceitual sobre a 2FA", não "Adiciona 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.
Faça push apenas no GitHub depois de fazer alguns commits. 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.

Como resolver conflitos de mesclagem

Ao tentar mesclar dois branches que contêm alterações diferentes na mesma parte de um arquivo, você verá 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.
"Resolver um conflito de merge no GitHub".

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

Na linha de comando, observe os arquivos que contêm conflitos de mesclagem.
Abra o primeiro desses arquivos no editor de texto.

No arquivo, procure os marcadores de conflitos de mesclagem.

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

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:
```
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.

Observação: 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.
No terminal, prepare os arquivos que acabou de modificar.
```
git add changed-file-1.md changed-file-2.md
```

Faça commit deles.

git commit -m "Resolves merge conflicts"

Faça o push das alterações confirmadas para o repositório remoto no GitHub.com.
```
git push
```

Como criar uma solicitação de pull

Recomendamos que você abra a pull request no GitHub antecipadamente. 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.

Observação: você pode acessar rapidamente as pull requests criadas clicando em Pull requests na parte superior de cada página do GitHub.

Para obter mais informações, confira "Como criar uma solicitação de pull".