> For the complete documentation index, see [llms.txt](https://cumbucadev.gitbook.io/github-essentials/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cumbucadev.gitbook.io/github-essentials/dia-11/forks-e-pull-requests/quando-o-upstream-e-atualizado-durante-o-seu-pr-sincronizando-o-fork.md). # Quando o Upstream é atualizado durante o seu PR: Sincronizando o Fork Quando você trabalha em um fork, é importante lembrar que o repositório original, chamado de upstream, continua evoluindo. Enquanto você faz alterações no seu fork, outras pessoas podem estar corrigindo bugs, adicionando funcionalidades, reorganizando o código ou melhorando a documentação. Se o seu fork ficar desatualizado em relação ao upstream, você pode enfrentar conflitos difíceis de resolver ao tentar enviar suas mudanças depois. Por isso, manter o fork sincronizado não é algo opcional. É uma boa prática essencial ao contribuir com projetos no GitHub. ## Quando você deve atualizar seu fork? Você deve sincronizar seu fork sempre que o repositório original tiver mudanças e você quiser continuar trabalhando de forma segura. Algumas situações comuns são: * **Antes de criar um Pull Request**\ Para garantir que sua contribuição está baseada na versão mais recente do projeto. * **Quando houver mudanças importantes no upstream**\ Isso ajuda a evitar conflitos grandes no futuro. * **Ao trabalhar em um fork por um período mais longo**\ Atualizações frequentes evitam que seu fork fique muito atrás. * **Quando o GitHub mostrar o aviso "This branch is behind..."**\ Esse aviso indica que seu fork está desatualizado. * **Quando você quiser usar novas funcionalidades ou correções**\ Se o upstream adicionou algo útil para o seu trabalho, você precisa sincronizar para ter acesso a isso. ## Entendendo o processo de sincronização Antes de ver o *como*, é importante entender o *fluxo correto*. A sincronização sempre acontece em **duas etapas**, nesta ordem: 1. Atualizar o **main do fork** com o **main do upstream** 2. Atualizar o **branch de trabalho** usando o **main do fork já atualizado** O fluxo correto é sempre: ``` upstream → main do fork → branch de desenvolvimento ``` Entender essa sequência evita confusão e problemas mais à frente. {% hint style="success" %} Sempre que você perceber que seu fork está atrás do upstream, sincronize antes de continuar trabalhando ou antes de abrir um Pull Request. Esse cuidado simples evita conflitos, facilita revisões e torna sua contribuição mais tranquila para você e para quem mantém o projeto. {% endhint %} ## Passo a Passo Antes de sincronizar qualquer coisa, vale olhar com calma o estado de cada repositório. Isso ajuda a entender o que está diferente e evita fazer passos no escuro. ### Verificando o histórico de commits Vamos começar comparando o histórico de commits de cada um dos repositórios e branches envolvidos. Primeiro, observe o histórico de commits do branch `main` do repositório original (upstream).
Depois, veja o histórico de commits do branch `main` do seu fork.
Por fim, observe o histórico de commits do branch em que você está trabalhando, por exemplo o branch `aprendizCumbucaDev`, que existe apenas no seu fork.
Agora vamos analisar esses históricos com mais atenção, olhando commit por commit. No `main` do upstream, vemos commits até o dia 30 de março. Além dos commits iniciais, existe um commit de merge de um Pull Request e um commit chamado "Adiciona frase a GARFO.md". Isso indica que o repositório original recebeu mudanças recentes que ainda não existem no fork.
No `main` do fork, o histórico para no dia 28 de março. Os commits mais recentes são "Adiciona instruções aos usuários" e, antes disso, os commits iniciais do projeto. Isso mostra que o `main` do fork não recebeu as mudanças feitas no upstream no dia 30.
Já no branch `aprendizCumbucaDev`, vemos algo importante. Ele contém um commit próprio, feito no dia 29 de março, chamado "Adiciona nova frase ao arquivo GARFO.md". Esse commit não existe nem no `main` do fork nem no `main` do upstream.
Isso nos mostra três coisas importantes. O upstream está à frente do `main` do fork. O branch `aprendizCumbucaDev` tem mudanças próprias que ainda não estão no `main`. E o fork como um todo está em um estado misto, com coisas novas de um lado e coisas faltando do outro. Essa análise deixa claro por que não é uma boa ideia sincronizar diretamente o branch secundário com o upstream. Primeiro, precisamos atualizar o `main` do fork. Só depois disso faz sentido atualizar o branch `aprendizCumbucaDev` com base nesse `main` já sincronizado. ### Identificando que o fork está desatualizado Agora, volte para a página principal do seu fork no GitHub. Ali mesmo, logo no topo do repositório, o GitHub mostra a seguinte mensagem: > This branch is 2 commits behind cumbucadev/PRimeiro-fork:main. Essa mensagem indica exatamente quantos commits o seu fork está atrás do upstream e já oferece uma opção para sincronizar. No nosso exemplo, esses dois commits que existem no upstream, mas ainda não existem no `main` do fork, são: * O commit de merge do Pull Request #2 * O commit chamado "Adiciona frase a GARFO.md" Esses commits apareceram no `main` do upstream no dia 30 de março e ainda não foram trazidos para o fork.
Esse aviso é um sinal claro de que está na hora de atualizar o fork. ### Atualizando primeiro o main do fork Sempre que possível, atualize primeiro o branch `main` do seu fork. Evite sincronizar diretamente o branch secundário com o upstream. Atualizar o `main` primeiro reduz o risco de conflitos e mantém uma estrutura mais organizada. Depois que o `main` do fork estiver atualizado, você usa ele como base para atualizar os outros branches. Na mensagem exibida pelo GitHub, clique na opção para sincronizar o fork.
Em seguida, clique em `Update Branch` .
Ao confirmar essa ação, o GitHub atualiza o `main` do seu fork com o `main` do upstream. Depois que a atualização termina, a mensagem no topo do repositório muda para: > This branch is up to date with cumbucadev/PRimeiro-fork:main.
Essa mensagem significa que o `main` do seu fork agora está completamente sincronizado com o `main` do upstream. Não há mais commits pendentes para trazer. Se você abrir novamente a opção **Sync fork**, o GitHub não vai mais mostrar o botão de atualização. Em vez disso, ele exibirá a mensagem: > 🇬🇧 This branch is not behind the upstream cumbucadev/PRimeiro-fork:main. > > No new commits to fetch. Enjoy your day! > > \ > 🇧🇷 Este branch não está atrasado em relação ao upstream cumbucadev/PRimeiro-fork:main.\ > Não há novos commits para buscar. Tenha um bom dia!
Isso confirma que não existe mais nenhuma diferença entre o `main` do fork e o `main` do repositório original naquele momento. Depois disso, vale fazer uma verificação simples no histórico de commits para garantir que a atualização realmente aconteceu. Volte para o histórico de commits do branch `main` do seu fork.
Agora, o histórico do `main` do fork deve ser igual ao histórico do `main` do upstream. Você deve ver também os commits do dia 30 de março, incluindo: * O commit de merge do Pull Request #2 * O commit "Adiciona frase a GARFO.md" Isso confirma visualmente que o `main` do fork foi atualizado corretamente e está alinhado com o repositório original. {% hint style="warning" %} **Importante!** Só foi possível fazer essa sincronização pela interface do GitHub porque **não havia conflitos** entre os dois branches. {% endhint %} ### Atualizando o branch secundário Com o `main` do fork já atualizado, é hora de levar essas mudanças para o branch em que você está trabalhando. #### Tentando pela interface do GitHub Para esta parte, vamos inicialmente tentar continuar utilizando a interface gráfica do GitHub. Caso não houvessem conflitos, essa etapa seria muito análoga a anterior e apenas com cliques tudo seria resolvido. Porém, como há um conflito - ambos os branches alteraram o arquivo `GARFO.md` na mesma linha - GitHub irá mostrar que não consegue fazer essa sincronização. Ao acessar a página principal do repositório já com o branch secundário selecionado, no nosso caso `aprendizCumbucaDev`, o GitHub mostra a seguinte mensagem no topo: > 🇬🇧 This branch is 1 commit ahead of and 2 commits behind cumbucadev/PRimeiro-fork:main. > > 🇧🇷 Este branch está 1 commit à frente e 2 commits atrás de cumbucadev/PRimeiro-fork:main.
Essa mensagem indica que o branch tem commits próprios que ainda não existem no `main`, mas ao mesmo tempo está atrasado em relação ao upstream. Se você tentar sincronizar pela interface, o GitHub exibirá: > 🇺🇸 This branch has conflicts that must be resolved. Discard 1 commit to make this branch match the upstream repository. 1 commit will be removed from this branch. You can resolve merge conflicts using the command line and a text editor.\ > \ > 🇧🇷 Este branch possui conflitos que precisam ser resolvidos.\ > Descarte 1 commit para que este branch corresponda ao repositório upstream.\ > Você pode resolver conflitos de merge usando a linha de comando e um editor de texto.
Sendo assim, o GitHub nos dá 3 opções: * **Botão Discard x commit**: Remove os commits existentes no branch secundário, descartando as alterações que você fez.\ Não use essa opção neste caso, pois você quer preservar tanto as suas mudanças quanto as mudanças vindas do upstream. * **Botão Open pull request**: Abre um Pull Request do branch secundário para o `upstream/main`, mas **não resolve o problema de sincronização**.\ Como o conflito continua existindo, esse Pull Request **não poderá ser mesclado**. * **Resolver os conflitos de mesclagem utilizando a linha de comando:** Indica que há conflitos e que eles precisam ser resolvidos manualmente no terminal.\ Esta é a opção correta e é o caminho que vamos seguir. O GitHub não resolve conflitos de código automaticamente. Sempre que conflitos aparecem, a forma **segura e correta** de resolvê-los é usando o **terminal**. #### Sincronizando o branch secundário pelo terminal **1. Atualizar o `main` local** Mesmo que você já tenha atualizado o `main` pelo GitHub, garanta que o `main` local esteja alinhado: ```shellscript git checkout main git pull origin main ``` **2. Atualizar o branch de trabalho** Agora que o `main` local está atualizado, vá para o branch de trabalho: ```shellscript git checkout aprendizCumbucaDev ``` E, em seguida, traga as atualizações do `main` para o branch aprendizCumbucaDev: ```shellscript git merge main ``` Como houve mudanças no mesmo local do mesmo arquivo, surgirá um conflito: ```bash Auto-merging GARFO.md CONFLICT (content): Merge conflict in GARFO.md Automatic merge failed; fix conflicts and then commit the result. ``` **3. Resolver o conflito** Verifique o status do repositório: ```shellscript ▶ git status On branch aprendizCumbucaDev You have unmerged paths. (fix conflicts and run "git commit") (use "git merge --abort" to abort the merge) Unmerged paths: (use "git add ..." to mark resolution) both modified: GARFO.md no changes added to commit (use "git add" and/or "git commit -a") ``` Verifique o arquivo que contém o conflito: ```md # Garfo - Por que é que se plantam garfos? Para depois colher. <<<<<<< HEAD - Nem vem de garfo que hoje é dia de sopa. ======= - Praticando forks no GitHub. >>>>>>> main ``` Resolva os conflitos, neste caso mantendo as duas alterações: ```md # Garfo - Por que é que se plantam garfos? Para depois colher. - Praticando forks no GitHub. - Nem vem de garfo que hoje é dia de sopa. ``` Adicione as alterações: ```bash git add GARFO.md ``` Verifique o status: ```bash ▶ git status On branch aprendizCumbucaDev All conflicts fixed but you are still merging. (use "git commit" to conclude merge) Changes to be committed: modified: GARFO.md ``` Faça o commit: ```shellscript ▶ git commit -m 'Atualiza mudanças do upstream' [aprendizCumbucaDev b3dadb7] Atualiza mudanças do upstream ``` Verifique o log com `git log --one-line` : ```shellscript b3dadb7 (HEAD -> aprendizCumbucaDev) Atualiza mudanças do upstream d7183f7 (origin/main, origin/HEAD, main) Merge pull request #2 from cumbucadev/camilamaia 9df7ccf Adiciona frase a GARFO.md 78a7b53 (origin/aprendizCumbucaDev) Adiciona nova frase ao arquivo GARFO.md 30352b8 Adiciona instruções aos usuários 681c88f Remove arquivos desnecessários 566468e Initial commit ``` **4. Publicando a atualização** Por fim, publique o branch atualizado no GitHub: ```shellscript git push origin aprendizCumbucaDev ``` Depois do push, a página do branch no GitHub será atualizada e a mensagem de branch passa a ser: > 🇬🇧 This branch is [2 commits ahead of](https://github.com/aprendizCumbucaDev/PRimeiro-fork/compare/cumbucadev%3APRimeiro-fork%3Amain...aprendizCumbucaDev) cumbucadev/PRimeiro-fork:main. > > 🇧🇷 Este branch está 2 commits à frente de cumbucadev/PRimeiro-fork:main.
E ao clicar no botão Sync Fork, novamente temos a mensagem que sinaliza que está tudo sincronizado de forma correta: > 🇬🇧 This branch is not behind the upstream cumbucadev/PRimeiro-fork:main. > > No new commits to fetch. Enjoy your day! > > 🇧🇷 Este branch não está atrasado em relação ao upstream cumbucadev/PRimeiro-fork:main. > > Não há novos commits para buscar. Tenha um bom dia!
Com isso, tanto o `main` do fork quanto o branch de trabalho ficam sincronizados com o upstream. E, ao final, o branch secundário passa a conter tanto as suas mudanças quanto as atualizações vindas do upstream, de forma clara e segura.
## Fazendo toda a sincronização pelo terminal (alternativa) Todo esse processo pode ser feito apenas pelo terminal através seguinte sequência de comandos: ```shellscript # adiciona um remote chamado `upstream` apontando para o reposiório original: git remote add upstream https://github.com/cumbucadev/PRimeiro-fork.git git checkout main git merge upstream/main # caso existam conflitos, resolvê-los git push origin main git checkout aprendizCumbucaDev git merge main # caso existam conflitos, resolvê-los git push origin aprendizCumbucaDev ``` Esse fluxo é ideal para quem quer entender exatamente o que está acontecendo em cada etapa e manter total controle sobre o processo. *** Neste ponto, seu fork está corretamente sincronizado com o repositório original: o `main` do fork reflete o estado atual do upstream, e o branch de trabalho contém tanto as suas alterações quanto as atualizações mais recentes do projeto, com os conflitos resolvidos de forma explícita e segura.\ Esse é exatamente o estado esperado antes de contribuir de volta para o repositório original. Com a base atualizada e o histórico organizado, você evita conflitos desnecessários, facilita a revisão do código e demonstra boas práticas de colaboração. Na próxima seção, vamos dar o passo final do fluxo de contribuição: abrir e mesclar o Pull Request, entendendo o que acontece nesse processo, quais cuidados tomar antes de clicar em *Merge* e como escolher a estratégia de mesclagem adequada. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cumbucadev.gitbook.io/github-essentials/dia-11/forks-e-pull-requests/quando-o-upstream-e-atualizado-durante-o-seu-pr-sincronizando-o-fork.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.