Usando o Git na Documentação do GitHub

Este artigo descreve o processo de criar um branch de tópicos no repositório da documentação, comprometer as alterações e empurrar as alterações de volta 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 espaço de código. Para saber mais, confira Clonar um repositório.

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

Para manter as ramificações locais sincronizadas com repositórios remotos e evitar conflitos de mesclagem, siga estas etapas ao trabalhar 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
```
Mude para um ramo de tópico ou crie um.
- Para iniciar um novo projeto, crie um ramo de tópico a partir de 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 ramo de 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 ramo de 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 stage do Git, da qual as alterações podem ser efetivadas. 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 realizará o commit das mudanças localmente. Agora você pode fazer push desse commit e de todos os outros commits não enviados 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.
Envie suas alterações para o 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 ramo sem argumentos adicionais.
```
git push --set-upstream origin YOUR-TOPIC-BRANCH
```
- Se você já executou o comando push desse branch antes e definiu um branch upstream para acompanhamento, 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 preliminares de muitos artigos ao mesmo tempo a fim de fornecer um esquema organizacional para os trabalhos subsequentes.
Se você estiver incorporando comentários ou quiser endereçar um conjunto de alterações a uma pessoa ou equipe específica 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 encerrar um problema, abra uma pull request e adicione "Closes #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.
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 modificações não commitadas no branch local quando terminar de trabalhar no final do 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 somente no GitHub depois de realizar 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.

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 integrar o main em um ramo de 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.

        [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github).

Resolver os conflitos de mesclagem mediante a edição do arquivo e a realização do 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 de upstream, pois elas podem ter sido feitas por motivos específicos que você desconheça.
No terminal, adicione o arquivo ou arquivos que acabou de modificar.
```
git add changed-file-1.md changed-file-2.md
```

Faça o commit dos arquivos.

git commit -m "Resolves merge conflicts"

Envie as alterações que foram confirmadas para o repositório remoto no site GitHub.
```
git push
```

Como criar uma solicitação de pull

Recomendamos que você abra a pull request no GitHub antecipadamente. Crie o pull request como um rascunho até estar pronto para que ele seja revisado. 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 saber mais, confira Como criar uma solicitação de pull.