Git: synchronizacja forka z upstream na 3 bezpieczne sposoby

TL;DR: wykonaj git fetch upstream && git merge upstream/main && git push origin main i fork jest na bieżąco. To cały workflow „git sync fork with upstream” w jednej linii — pociągnij zmiany z projektu, który sforkowałeś, i wypchnij je do swojej kopii. Jeśli wolisz liniową historię, zamień merge na git rebase upstream/main i wypchnij force. A jeśli nigdy nie podłączyłeś remote’a upstream, zacznij od kroku 1 poniżej, bo brakujący remote to powód numer jeden, dla którego fork „nie chce się zsynchronizować”. Cała reszta — rebase, przycisk synchronizacji na GitHubie, rozjechane gałęzie, których nie da się wypchnąć — to szczegóły na wierzchu tych trzech komend.

Co znaczy zsynchronizować forka z upstreamem?

Fork to twoja kopia cudzego repozytorium na GitHubie. Oryginał to upstream; twoja kopia to origin. Forki na GitHubie nie aktualizują się same — gdy maintainerzy mergują pull request, twoja kopia trzyma wczorajszy kod. Zsynchronizowanie forka znaczy pociągnięcie nowych commitów z upstreamu do twojego forka, tak żeby twoja gałąź odpowiadała — albo przynajmniej zawierała — aktualny stan projektu.

To ma znaczenie z dwóch powodów. Po pierwsze, kontrybucje: każdy pull request otwarty ze staryego forka niesie dodatkowy szum, a maintainerzy poproszą o aktualizację przed mergem. Po drugie, self-hosting albo nauka: jeśli trzymasz forka na produkcji albo po prostu czytasz kod, miesięczny fork to miesiąc poprawek błędów, których nie masz.

Jak zsynchronizować forka z upstreamem z linii poleceń?

Trzy kroki: raz zadeklaruj upstream, pociągnij z niego, potem zmerguj i wypchnij. Podłączenie jest trwałe — następnym razem wpisujesz tylko kroki 2 i 3.

Krok 1 — dodaj remote upstream (raz na klon).

# wewnątrz lokalnego klonu forka
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git
git remote -v   # potwierdź: origin -> twój fork, upstream -> oryginał

Właściwy URL znajdziesz na stronie oryginalnego repo: zielony przycisk Code. Klasyczny błąd to skierowanie obu remote’ów na twój fork — wtedy „synchronizacja” po cichu nie robi nic, bo ciągnąłeś z kopii równie starej jak twoja.

Krok 2 — pobierz i zmerguj gałąź upstream.

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

To standardowa odpowiedź na „git sync fork with upstream command line”. Fast-forward to normalny wynik — main na twoim forku nie miała nic nowego, więc po prostu przesuwa się do upstream/main i żaden merge commit nie powstaje.

Krok 3 — powtarzaj na żądanie. Nie ma nic do zapamiętania poza git fetch upstream && git merge upstream/main && git push origin main. Żeby przed mergem zobaczyć, jak daleko jesteś w tyle, wykonaj po fetchu git rev-list --count main..upstream/main.

Rebase czy merge przy synchronizacji forka?

Obie drogi trafiają z tym samym kodem do twojego forka; różnią się historią, jaką zostawiają. Wybierz jedną politykę na repo i się jej trzymaj:

Metoda	Komenda	Efekt w historii	Najlepsze dla
Merge	git merge upstream/main	Dodatkowy merge commit przy rozjechanych gałęziach	Gałęzie feature’owe z otwartymi PR-ami — niczego nie przepisuje
Rebase	git rebase upstream/main	Twoje commity odgrywane na wierzchu, liniowa historia	Czysty main twojego forka; rozjechane forki, które chcesz wyprostować
UI GitHuba	Przycisk Sync branch / merge PR-a	To samo co merge	Szybkie dogonienie bez otwartego klonu

Wariant synchronizacji z rebasem:

git fetch upstream
git rebase upstream/main
git push --force-with-lease origin main

Force push jest konieczny, bo rebase przepisuje ID commitów — zdalna gałąź twojego forka nie jest już potomkiem lokalnej. Zawsze wybieraj --force-with-lease zamiast --force: odmówi nadpisania zdalnej gałęzi, jeśli ktoś (albo twoja druga maszyna) wypchnął w międzyczasie, co czyni niebezpieczną komendę bezpieczną domyślnie.

Jedna reguła warta wytatuowania na nadgarstku: nigdy nie rób rebasu gałęzi z otwartym pull requestem, chyba że wiesz, co robisz — rebase zmienia ID commitów, co potrafi odpiąć otwarty PR od jego commitów. main synchronizuj mergem (albo rób jej rebase przed rozpoczęciem nowej roboty), a gałęzie PR-ów trzymaj z dala.

Dlaczego mój fork nie synchronizuje się z upstreamem?

Czterech zwykłych podejrzanych, w kolejności, w jakiej pojawiają się w prawdziwych terminalach:

1. Brak remote’a upstream — git remote -v pokazuje tylko origin. Objaw: git fetch upstream pada z 'upstream' does not appear to be a git repository. Naprawa: krok 1 wyżej.
2. Pociągnąłeś, ale nigdy nie zmergowałeś — fetch aktualizuje upstream/main w twoim lokalnym repo, ale nie rusza żadnej gałęzi roboczej. Objaw: git log wygląda staro po udanym fetchu. Naprawa: git merge upstream/main.
3. Rozjechana historia — commitowałeś do main swojego forka, a upstream też ruszył do przodu. git pull wtedy narzeka na niepowiązane historie albo wymusza merge. Naprawa, jeśli upstream ma wygrać: git reset --hard upstream/main (wyrzuca twoje lokalne commity z samego maina — sprawdź git stash list albo najpierw zrób kopię na gałęzi; jeśli zły reset już się wydarzył, droga ratunku jest ta sama co przy cofaniu ostatniego commita: git reflog wciąż pamięta stary czubek).
4. Push odrzucony jako non-fast-forward po rebasie — zrobiłeś rebase, ale wypchnąłeś normalnie. Naprawa: git push --force-with-lease origin main.

Piąty, rzadki przypadek: repo upstream zmieniło nazwę albo zostało usunięte, więc nawet URL z kroku 1 zwraca 404. GitHub przekierowuje repo po zmianie nazwy, więc twarda porażka zwykle znaczy usunięte albo prywatne — nie ma czego synchronizować.

Czy da się zsynchronizować fork ze strony GitHuba?

Tak. Na stronie twojego forka rozwijana lista gałęzi pokazuje przycisk Sync fork, ilekroć twoja gałąź jest w tyle; jedno kliknięcie wciąga upstream. Głębiej na stronie to samo działa jako pull request: otwórz PR z upstream/main do main swojego forka i zmerguj go.

Granice przycisku mówią, kiedy wracać do CLI: robi tylko fast-forward albo merge — nie robi rebasu i odmawia stanowczo, gdy gałęzie się rozjechały, każąc wyrzucić commity albo użyć linii poleceń. Synchronizuje też tylko gałąź domyślną. Na wszystko ponad proste dogonienie narzędziem są te trzy komendy wyżej.

Jak często synchronizować fork?

Przed każdą nową robotą to uczciwa odpowiedź: gałęzuj się ze świeżego maina, a żaden otwarty PR nie zaczyna się od „to na wersji sprzed trzech tygodni”. Dla forków, do których aktywnie kontrybuujesz, dzienna synchronizacja maina kosztuje sekundy. Dla forka, który tylko czytasz albo deployujesz, synchronizuj, gdy upstream wypuści coś, czego chcesz — zasubskrybuj feed wydań oryginalnego repo i synchronizuj przy wydaniu. Synchronizacja jest tania właśnie dlatego, że jest rutyną; fork spóźniony o pół roku często wymaga chirurgii zamiast merge’a, i tak „zsynchronizuj mi forka” staje się popołudniem.

Ściągawka

# jednorazowa konfiguracja
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git

# rutynowa synchronizacja (polityka merge)
git fetch upstream && git merge upstream/main && git push origin main

# rutynowa synchronizacja (polityka rebase, liniowa historia)
git fetch upstream && git rebase upstream/main && git push --force-with-lease origin main

# jak daleko w tyle jestem?
git fetch upstream && git rev-list --count main..upstream/main

# rozjechane bez ratunku — ustaw main identyczny z upstreamem (destrukcyjne)
git fetch upstream && git reset --hard upstream/main && git push --force-with-lease origin main

Trzymaj rutynową dwulinijkę w pamięci mięśniowej, a rozjechany fork pozostanie ciekawostką do przeczytania, nie problemem do naprawienia. Jeśli twoje porządki w gicie sięgają serwerów, ściągawka z journalctl pokrywa drugą połowę utrzymywania historii maszyny w czytelności.