Sincronizar un fork con upstream — tres métodos seguros

■ espacio · carril de prosa

EL FLUJO

Una sincronización siempre viaja en una dirección — upstream → tu main local → origin. Nada del fork fluye de vuelta a upstream; para eso están los pull requests.

origin = tu fork · upstream = el proyecto que forkeaste — el error común es apuntar ambos remotes a tu fork; entonces una "sincronización" silenciosamente no hace nada, porque hiciste fetch de una copia tan rancia como la tuya

PASO 1 — CABLEA EL REMOTE (UNA VEZ POR CLON)

# dentro de tu clon local del fork
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git
git remote -v   # confirma: origin -> tu fork, upstream -> el original

Encuentra la URL correcta en la página del repo original, bajo el botón verde Code. Este cableado es permanente — todo lo de abajo es lo que tecleas la próxima vez.

PASO 2 — FETCH, MERGE, PUSH

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

verifica: git rev-list --count main..upstream/main → 12 antes del merge → 0 después

Un fast-forward es el desenlace normal — tu main no tenía nada nuevo, así que simplemente se desliza hacia adelante hasta upstream/main y no se crea commit de merge. Para ver cuánto te has quedado antes de fusionar: git rev-list --count main..upstream/main tras el fetch. Esa es toda la rutina; el paso 3 es recordar que existe: git fetch upstream && git merge upstream/main && git push origin main.

¿MERGE O REBASE?

Ambos aterrizan el mismo código en tu fork; se diferencian en el historial que dejan atrás. Elige una política por repo y sé constante:

# la variante rebase, historial lineal:
git fetch upstream
git rebase upstream/main
git push --force-with-lease origin main

El force push es obligatorio porque el rebase reescribe los IDs de commits — la rama remota de tu fork ya no desciende de la local. Prefiere siempre --force-with-lease sobre --force : se niega a sobreescribir el remoto si alguien (u otra máquina tuya) empujó mientras tanto, lo que vuelve segura la comando peligrosa por defecto. Y la regla de oro: never rebase a branch that has an open pull request unless you know what you are doing — rebasing changes commit IDs, which can detach an open PR from its commits. Sync main con merge, deja fuera las ramas de PR.

"MI FORK NO SE SINCRONIZA" — LOS CUATRO SOSPECHOSOS DE SIEMPRE

1. Sin remote upstream remote — git remote -v solo muestra origin. Symptom: falla con fails with 'upstream' does not appear to be a git repository. Fix: step 1.
2. Fetch pero nunca merge — el fetch actualiza upstream/main localmente pero no toca ninguna rama de trabajo. Síntoma: git log se ve viejo tras un fetch exitoso. Arreglo: git merge upstream/main.
3. Historial divergido — you committed to your fork's main y upstream también se movió. Arreglo, si quieres que gane upstream: git reset --hard upstream/main — descarta tus commits exclusivos de tu main local, así que respaldalos primero en una rama; si ya ocurrió un reset malo, git reflog aún conoce la punta vieja.
4. Push rechazado como non-fast-forward tras un rebase — you rebased but pushed normally. Fix: git push --force-with-lease origin main.

Un quinto caso, raro: el repo upstream fue renombrado o borrado, así que hasta la URL del paso 1 da 404. GitHub redirige los repos renombrados, así que un fallo duro suele significar borrado o hecho privado — no hay nada a qué sincronizarse.

EL BOTÓN

Sí, la web puede hacerlo: en la página de tu fork, el desplegable de rama muestra un botón Sync fork button whenever your branch is behind; one click pulls upstream in. Below the fold, the same thing works as a pull request from en cuanto tu rama va atrás; un clic trae upstream. Más abajo, lo mismo funciona como pull request de into your fork's main. Los límites del botón explican cuándo volver al CLI: solo hace fast-forward o merge — no rebasea, y se niega de plano cuando las ramas divergieron, diciéndote que descartes commits o uses la línea de comandos. También sincroniza solo la rama por defecto. Para todo lo que pase de un simple ponerse al día, los tres comandos son la herramienta.

¿CON QUÉ FRECUENCIA?

Antes de cada nuevo trabajo es la respuesta honesta: ramifica desde un main fresco, y ningún PR que abras empieza con "esto se basa en una versión de hace tres semanas". Para forks a los que contribuyes activamente, una sincronización diaria o por sesión de main cuesta segundos. Para un fork que solo lees o despliegas, sincroniza cuando upstream publique algo que quieras — suscríbete al feed de releases del repo original y sincroniza en cada release. Sincronizar es barato precisamente porque es rutina; un fork con seis meses de retraso suele necesitar cirugía en vez de un merge, y así es como "sincroniza mi fork" se convierte en una tarde.

08LA CHULETA

# configuración única
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git

# sincronización de rutina (política merge)
git fetch upstream && git merge upstream/main && git push origin main

# sincronización de rutina (política rebase, historial lineal)
git fetch upstream && git rebase upstream/main && git push --force-with-lease origin main

# ¿de cuánto estoy por detrás?
git fetch upstream && git rev-list --count main..upstream/main

# divergido sin remedio — hacer main idéntico a upstream (destructivo)
git fetch upstream && git reset --hard upstream/main && git push --force-with-lease origin main

Guarda la rutina de dos líneas en tu memoria muscular y el fork divergido seguirá siendo una curiosidad que lees, no un problema que arreglas.

fin de la página de sincronización · nada descargado · todo local