Fluxo de trabalho de fork

Visão geral

O fluxo de trabalho de fork é o modelo padrão para projetos de código aberto e qualquer situação em que os contribuidores não têm acesso de push direto ao repositório principal. Em vez de fazer push para um repositório compartilhado, cada contribuidor trabalha em sua própria cópia no lado do servidor — um fork — e propõe alterações por meio de um pull request. É assim que milhões de contribuições chegam a projetos no GitHub e no GitLab todos os dias.

Esta página explica o que é um fork, como ele difere de um fluxo de trabalho com repositório compartilhado, os comandos exatos para clonar, configurar remotes, fazer push e abrir um pull request e — mais importante — como manter seu fork sincronizado para que suas contribuições sejam fáceis de mesclar.

A diferença fundamental

No fluxo de trabalho de feature branch, todos fazem push de branches para um único repositório compartilhado. O fluxo de fork adiciona uma camada: agora existem dois repositórios no lado do servidor — o repositório oficial upstream, no qual você não pode escrever, e o seu fork, que você controla completamente. Você faz push para o seu fork e pede ao upstream que faça pull a partir dele.

Isso é às vezes chamado de fluxo triangular por causa de como as três cópias se relacionam:

        upstream (official repo, read-only to you)
          ▲   │
   pull   │   │ fork (one click, server-side)
  request │   ▼
        your fork (origin) ──clone──▶ your laptop
                            ◀──push──

Você faz fetch de upstream, push para origin (seu fork) e o pull request é a ponte que pede a um mantenedor que faça pull do seu branch do seu fork para o upstream.

Passo a passo

1. Fork do repositório upstream na plataforma de hospedagem. Isso cria your-fork na sua conta — uma cópia completa no lado do servidor.

2. Clone do seu fork para a sua máquina:

git clone https://github.com/you/project.git
cd project

3. Adicione o upstream como remote para poder baixar as alterações mais recentes do projeto:

git remote add upstream https://github.com/original/project.git

Seu clone agora tem dois remotes. Verifique-os com git remote -v:

origin    https://github.com/you/project.git (fetch)
origin    https://github.com/you/project.git (push)
upstream  https://github.com/original/project.git (fetch)
upstream  https://github.com/original/project.git (push)

origin aponta para o seu fork (onde você faz push); upstream aponta para o repositório oficial (de onde você faz fetch). Veja git remote para gerenciar esses remotes.

4. Crie um branch e trabalhe. Sempre crie branches a partir de um main atualizado — nunca faça commit diretamente no main do seu fork, para que ele permaneça como um espelho limpo do upstream:

git switch -c fix/typo-in-docs
# ...make changes and commit...
git push -u origin fix/typo-in-docs

O flag -u (--set-upstream) vincula seu branch local ao branch no seu fork, para que depois você possa apenas executar git push.

5. Abra um pull request do branch do seu fork para o branch main do upstream. Na interface web isso é um botão; com a CLI do GitHub você pode fazer isso pelo terminal:

gh pr create --base main --head you:fix/typo-in-docs

Os mantenedores revisam, solicitam alterações se necessário, e fazem merge quando estiverem satisfeitos. Se pedirem edições, faça commit e execute git push novamente — o pull request aberto é atualizado automaticamente.

Mantendo o fork sincronizado com o upstream

O projeto continua evoluindo enquanto você trabalha, então atualize seu fork a partir do upstream antes de iniciar novos branches. Use git fetch para baixar os commits do upstream e, em seguida, git merge (ou rebase) para incorporá-los:

git switch main
git fetch upstream
git merge upstream/main      # fast-forward main onto upstream
git push origin main         # update your fork's main on the server

Como você nunca faz commit diretamente no main, esse merge é sempre um fast-forward limpo — sem conflitos. Você pode garantir isso com git merge --ff-only upstream/main, que falha imediatamente se o main tiver divergido.

Atualizando um branch de feature em andamento

Se o seu branch ficar desatualizado enquanto uma revisão se estende, traga os novos commits do upstream para ele. O rebase mantém um histórico linear que os mantenedores geralmente preferem:

git fetch upstream
git switch fix/typo-in-docs
git rebase upstream/main
git push --force-with-lease    # rewrite your fork's branch safely

--force-with-lease recusa sobrescrever o remote se outra pessoa tiver feito push enquanto isso, tornando-o muito mais seguro do que um simples --force. Se preferir evitar reescrever o histórico, execute git merge upstream/main em vez disso. Veja git rebase e conflitos de merge para lidar com os detalhes.

Por que funciona

O modelo de fork permite que um projeto aceite contribuições de qualquer pessoa enquanto mantém o repositório oficial protegido — apenas os mantenedores podem fazer merge. Os contribuidores não precisam de permissões especiais, a revisão acontece de forma pública em cada pull request e o histórico do upstream permanece limpo. Para colaboração em larga escala com usuários não confiáveis, é o mais seguro dos fluxos de trabalho Git comuns.

Use-o quando os contribuidores não tiverem acesso de push (a maioria dos projetos de código aberto). Quando todos estão na mesma equipe e são confiáveis, o fluxo de feature branch ou o Gitflow mais simples evita o fork extra. Compare-os lado a lado em Fluxos de trabalho Git.

Prática