Flujo de trabajo con forks

Visión general

El flujo de trabajo con forks es el modelo estándar para proyectos de código abierto y cualquier entorno donde los colaboradores no tienen acceso directo de escritura al repositorio principal. En lugar de hacer push a un repositorio compartido, cada colaborador trabaja en su propia copia en el servidor — un fork — y propone cambios mediante un pull request. Así es como millones de contribuciones llegan cada día a proyectos en GitHub y GitLab.

Esta página explica qué es un fork, cómo se diferencia del flujo de trabajo con repositorio compartido, los comandos exactos para clonar, configurar remotos, hacer push y abrir un pull request y, lo más importante, cómo mantener tu fork sincronizado para que tus contribuciones sean fáciles de fusionar.

La diferencia clave

En el flujo de trabajo con ramas de características, todos hacen push de sus ramas a un único repositorio compartido. El flujo de trabajo con forks añade una capa: ahora existen dos repositorios en el servidor — el repositorio oficial upstream, al que no puedes escribir, y tu fork, que controlas completamente. Haces push a tu fork y pides al upstream que haga pull desde él.

Esto se denomina a veces flujo de trabajo triangular por la relación entre las tres copias:

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

Haces fetch desde upstream, push a origin (tu fork), y el pull request es el puente que pide a un mantenedor que traiga tu rama desde tu fork al upstream.

Paso a paso

1. Fork: haz fork del repositorio upstream en la plataforma de alojamiento. Esto crea tu-fork bajo tu cuenta — una copia completa en el servidor.

2. Clone: clona tu fork en tu máquina:

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

3. Añade upstream como remoto para poder obtener los últimos cambios del proyecto:

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

Tu clon ahora tiene dos remotos. Verifícalos con 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 apunta a tu fork (donde haces push); upstream apunta al repositorio oficial (donde haces fetch). Consulta git remote para gestionar estos remotos.

4. Crea una rama y trabaja. Crea siempre la rama a partir de un main actualizado — nunca hagas commits directamente en el main de tu fork, para que se mantenga como un espejo limpio del upstream:

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

La opción -u (--set-upstream) vincula tu rama local con la del fork, de modo que más adelante bastará con ejecutar git push.

5. Abre un pull request desde la rama de tu fork a la rama main del upstream. En la interfaz web es un botón; con la CLI de GitHub puedes hacerlo desde el terminal:

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

Los mantenedores lo revisan, solicitan cambios si es necesario y lo fusionan cuando están satisfechos. Si piden modificaciones, haz commit y vuelve a ejecutar git push — el pull request abierto se actualiza automáticamente.

Mantener tu fork sincronizado con upstream

El proyecto sigue avanzando mientras trabajas, así que actualiza tu fork desde upstream antes de comenzar nuevas ramas. Usa git fetch para descargar los commits del upstream y luego git merge (o rebase) para incorporarlos:

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 nunca haces commits directamente en main, esta fusión siempre es un fast-forward limpio — sin conflictos. Puedes garantizarlo con git merge --ff-only upstream/main, que falla claramente si main ha divergido.

Actualizar una rama en progreso

Si tu rama se queda atrás mientras una revisión se prolonga, incorpora los nuevos commits del upstream. El rebase mantiene un historial lineal que los mantenedores suelen preferir:

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 se niega a sobreescribir el remoto si alguien más ha hecho push mientras tanto, lo que lo hace mucho más seguro que un --force simple. Si prefieres no reescribir el historial, ejecuta git merge upstream/main en su lugar. Consulta git rebase y conflictos de fusión para gestionar los detalles.

Por qué funciona

El modelo de forks permite que un proyecto acepte contribuciones de cualquier persona manteniendo el repositorio oficial bajo control — solo los mantenedores pueden fusionar. Los colaboradores no necesitan permisos especiales, la revisión se realiza de forma pública en cada pull request y el historial del upstream se mantiene limpio. Para la colaboración a gran escala con colaboradores no confiables, es el más seguro de los flujos de trabajo comunes de Git.

Úsalo cuando los colaboradores no tienen acceso de escritura (la mayoría del código abierto). Cuando todos son del mismo equipo y de confianza, el más sencillo flujo de trabajo con ramas de características o Gitflow evita el fork adicional. Compáralos lado a lado en flujos de trabajo de Git.

Práctica