En la lección anterior usamos git push varias veces sin explicarlo. Tocaba: había que poner el proyecto en el servidor para poder estudiar la recepción. Ahora le damos la vuelta al canal y desmenuzamos el comando que envía.

git push es el comando con consecuencias para los demás. Todo lo que has hecho hasta ahora —confirmar, ramificar, fusionar, incluso equivocarte— ocurría dentro de tu .git/ y se podía deshacer sin que nadie se enterara. Un push cambia el repositorio que todo el equipo usa como referencia. Lo que envías, otros lo descargan; y lo que borras del servidor, otros dejan de tener.

Por eso esta lección dedica tanto espacio a los rechazos y a las opciones de forzado. Saber enviar es fácil; saber por qué el servidor te dice que no, y qué es seguro hacer entonces, es lo que distingue a alguien que no destruye el trabajo de sus compañeros.

Ana envía por fin main y sus ramas al servidor del equipo, y Bruno y Carla las reciben.

1. Qué envía exactamente git push
2. El primer envío: git push -u origin main
3. Qué hace exactamente el -u
4. El refspec de envío
5. Las formas abreviadas y push.default
6. Cuando el servidor dice que no: non-fast-forward
7. --force-with-lease frente a --force
8. Borrar una rama en el servidor
9. Enviar etiquetas
10. Ana publica sus ramas; Bruno y Carla las reciben

La definición precisa, que es más estrecha de lo que la gente imagina:

git push hace dos cosas: sube al remoto los objetos que le faltan y le pide que actualice una referencia para que apunte a un commit concreto.

Objetos y un puntero. Nada más.

Lo que NO envía:

• Tu directorio de trabajo. Los ficheros modificados sin confirmar se quedan en tu disco. Si has editado app.js y no has hecho commit, ese cambio no sale de tu máquina por mucho push que hagas.
• Tu índice. El área de preparación es tuya y personal.
• Tu configuración. .git/config no viaja: los remotos, alias y ajustes de cada persona son suyos.
• Tus otras ramas, salvo que las pidas explícitamente.
• Tu reflog. El registro de tus movimientos es local.
• Los ficheros ignorados. Lo que no está en un commit, no existe para el push.

Esa primera es la más importante y la fuente de un desconcierto clásico: "he hecho push y mi compañero no ve el cambio". Casi siempre significa que el cambio no llegó a confirmarse. Solo viaja lo que está dentro de un commit.

Ese penúltimo paso —la comprobación de fast-forward— es el corazón del apartado 6 y la razón de casi todos los rechazos.

Y una consecuencia interesante: el envío es incremental. Git calcula qué objetos le faltan al servidor y manda solo esos, comprimidos en un packfile. Enviar el commit número mil de un proyecto no cuesta más que enviar el segundo.

Volvamos al momento en que Ana publicó. Su repositorio tenía el remoto registrado (lección 04-02) y la autenticación resuelta (lección 04-03), pero nunca había enviado nada:

Vale la pena leer esa salida entera, porque cuenta todo el proceso:

Fíjate en la eficiencia: toda la historia del proyecto —cuatro commits base, dos fusiones, un squash, un conflicto resuelto— cabe en 4,87 KB. Esa es la compresión delta del modelo de datos que estudiamos en la lección 01-04.

Y una comprobación desde el servidor:

El repositorio que estaba vacío ya tiene una rama y una historia.

-u es la abreviatura de --set-upstream, y aparece en absolutamente todos los tutoriales de Git sin que casi ninguno explique qué hace.

Lo que hace es escribir dos líneas en .git/config:

Esa sección [branch "main"] es la rama de seguimiento: la asociación entre tu rama local main y la rama main de origin. Y a partir de ese momento cambian varias cosas:

La comprobación inmediata:

Ese "up to date with 'origin/main'" solo aparece si hay seguimiento configurado. Sin él, git status no tendría con qué comparar.

El -u solo hace falta la primera vez que envías una rama. Después, la configuración ya está escrita y git push a secas funciona.

Y recuerda que en la lección 01-06 configuramos esto:

Con ese ajuste (disponible desde Git 2.37), el -u es innecesario: al enviar una rama nueva, Git configura el seguimiento automáticamente. Ana podría haber escrito simplemente git push y el resultado habría sido idéntico. Lo hemos usado explícitamente para que veas lo que ocurre por debajo.

Todo lo relativo a las ramas de seguimiento —cómo se consultan, cómo se cambian, qué significa exactamente ese "2 commits ahead"— es el tema de la lección 04-06, la que cierra el módulo.

En la lección 04-02 desmenuzamos el refspec de descarga. El de envío usa exactamente la misma sintaxis, y verlo cierra el círculo.

La forma completa de un push es:

Leído: "envía mi rama main y actualiza con ella la rama main del servidor."

Comparado con el refspec de descarga, la lógica es idéntica y solo se invierte la dirección:

En los dos casos, izquierda = de dónde sale, derecha = a dónde va. Una vez lo ves así, deja de ser sintaxis arbitraria.

El tercero, HEAD:main, es útil cuando estás en HEAD desacoplado o en una rama con nombre local distinto y quieres enviar lo que tienes a main.

Estas dos líneas son equivalentes:

Git expande los nombres cortos. Pero hay un caso en que la forma completa es obligatoria: cuando la rama de destino no existe todavía y el nombre es ambiguo. Si en el servidor hubiera una etiqueta llamada revision y quisieras crear una rama con ese nombre, Git no sabría qué quieres:

La solución es ser explícito:

Si dejas el lado izquierdo vacío, estás enviando nada a esa referencia, lo cual la borra:

Es la sintaxis antigua de borrado, y la vemos en el apartado 8.

En el día a día casi nadie escribe el refspec completo. Estas son las formas cortas y lo que significa cada una:

La forma 4 es la que usarás el 95 % de las veces, y su comportamiento depende de un ajuste que ya configuramos en la lección 01-06:

Los valores posibles y qué hacen:

matching merece una advertencia histórica. Era el valor por defecto hasta Git 2.0, y provocaba una sorpresa desagradable: escribías git push pensando en enviar la rama en la que estabas, y Git enviaba de golpe las ocho ramas locales que tenían homónima en el servidor, incluidos experimentos a medias que no querías publicar. Cambiarlo a simple fue una de las mejores decisiones de Git. No lo pongas en matching.

Y una opción que sí es útil cuando de verdad quieres enviar varias:

Explícito y consciente, que es como debe ser.

Este es el rechazo más frecuente de Git y el que hay que entender de verdad.

Bruno se pone a trabajar por la mañana, hace dos commits y envía:

El servidor tiene commits que tú no tienes. Mientras Bruno trabajaba, Ana envió los suyos. El grafo está así:

Los dos partieron de c2a8f1e y cada uno avanzó por su lado. Han divergido, exactamente el concepto de la lección 03-01.

Si Git aceptara el envío de Bruno, la referencia main del servidor pasaría de b4d7e93 a 3e9c2a5. Y como b4d7e93 no es un antepasado de 3e9c2a5, los dos commits de Ana dejarían de ser alcanzables desde ninguna rama: desaparecerían del proyecto sin que nadie se enterase, y cualquiera que clonara después no vería ni rastro de ellos.

Por eso Git rechaza el envío: para no destruir trabajo ajeno. La regla es que una referencia del servidor solo puede avanzar de forma fast-forward, es decir, hacia un descendiente de donde estaba. Es la misma noción de fast-forward del módulo 3, aplicada ahora como medida de protección.

Y aquí conviene relacionar dos cosas. Recuerda de la lección 04-02 que el refspec de descarga lleva un + delante:

Ese + permite actualizaciones no fast-forward en tus referencias remotas, porque su trabajo es reflejar el servidor sea cual sea su estado. En el envío no hay ningún + por defecto, y es deliberado: hacia dentro, permisivo; hacia fuera, protector.

El procedimiento es siempre el mismo, y es exactamente lo que aprendiste en la lección anterior:

Con pull.ff only configurado, el paso 3 en forma de git pull se detendrá diciendo Not possible to fast-forward, porque hay divergencia real y Git no decide por ti. En ese punto tienes que integrar explícitamente.

Lo que nunca debes hacer es lo que sugiere el instinto y algún que otro consejo malintencionado de internet:

Eso sobrescribe la referencia del servidor con tu versión, y los commits de Ana quedan huérfanos. Ella los recuperará de su propio disco, sí, pero cualquiera que clone en ese intervalo no los verá, y el desconcierto está garantizado.

Este apartado cubre la causa y la salida básica. El tratamiento completo de la divergencia —cómo decidir entre fusionar, reaplicar o replantear; qué hacer si además hay conflictos; cómo salir de los casos enredados— es el tema de la lección 09-03: Resolviendo Divergencias con el Remoto. Aquí quédate con tres ideas:

1. El rechazo es una protección, no un fallo.
2. La causa es siempre la misma: el remoto tiene commits que tú no tienes.
3. La salida por defecto es integrar primero y enviar después.

Hay situaciones legítimas en las que necesitas sobrescribir una rama del servidor: has reescrito tu propia rama de trabajo (con las técnicas del módulo 5) y el resultado ya no es descendiente de lo que hay publicado. En esos casos, el envío normal será rechazado con toda la razón, y hay que forzar.

Pero hay dos formas de forzar, y la diferencia entre ellas puede ser el trabajo de una tarde de un compañero.

Git sobrescribe la referencia del servidor sin comprobar nada. Si alguien había enviado algo mientras tanto, sus commits quedan huérfanos.

Git compara el valor actual de la referencia en el servidor con tu origin/funcionalidad/orden-alfabetico, es decir, con la última foto que tienes. Si coinciden, sobrescribe. Si no coinciden —porque alguien ha enviado algo desde tu último fetch—, rechaza el envío:

La palabra lease es "arrendamiento": tú tenías reservada la referencia en un estado concreto, y si ha cambiado, el contrato se rompe y no se escribe nada.

La protección se basa en tu referencia remota local. Y eso abre un agujero:

Si haces fetch justo antes, tu origin/rama se actualiza con lo que el compañero acaba de enviar, la comparación coincide y --force-with-lease acepta encantado… sobrescribiendo precisamente lo que la opción debía protegerte de sobrescribir.

Hay dos formas de hacerlo bien:

Primera: mirar antes de forzar. Un fetch seguido de una inspección deliberada:

Segunda, y mejor: decir explícitamente qué valor esperas.

Aquí no dependes de ninguna foto: le dices a Git "solo escribe si el servidor está exactamente en 9d1e4b7". Es la forma más segura, y la que conviene usar en scripts.

Desde Git 2.30 existe además una opción complementaria:

Comprueba, además, que los commits que hay en el servidor están incluidos en lo que vas a enviar, es decir, que realmente los has integrado y no simplemente descargado.

1. Nunca fuerces main, develop ni ninguna rama compartida. Si el equipo trabaja sobre ella, reescribirla obliga a todo el mundo a resolver un lío. Y es exactamente lo que impiden las ramas protegidas de las plataformas.
2. Fuerza solo ramas tuyas, de trabajo, que nadie más esté usando.
3. Usa siempre --force-with-lease. Convierte --force en una palabra que no escribes.
4. Avisa al equipo si fuerzas una rama que alguien pueda tener clonada.
5. Si dudas, no fuerces. Un historial con un commit de fusión de más no ha matado nunca a nadie; un --force sobre main un viernes, casi.

Un alias que ayuda a que la buena costumbre sea la más cómoda:

Y una nota tranquilizadora, porque conviene no vivir con miedo: si alguien fuerza y destruye commits, casi siempre se pueden recuperar. Quien los tenía en su disco los conserva; y en el servidor, el reflog o las herramientas de la plataforma suelen permitir rescatarlos. Es un lío, no una catástrofe. La recuperación se estudia en la lección 09-04.

Cuando una rama se integra, hay que borrarla en los dos sitios: en tu repositorio (con git branch -d, lección 03-06) y en el servidor.

Legible y difícil de confundir. Es la que debes usar.

Hace exactamente lo mismo, y ahora entiendes por qué: es el refspec <origen>:<destino> con el origen vacío. Estás enviando "nada" a esa referencia del servidor, lo cual la elimina.

La verás en documentación y en scripts antiguos, así que conviene reconocerla. Pero también conviene saber el riesgo: un espacio de más y estás borrando algo que no querías. Compara:

Un carácter de diferencia entre publicar y destruir. Por eso --delete es mejor.

Borrar una rama en el servidor no borra las referencias que tienen tus compañeros. Cada uno tendrá que limpiarlas, como vimos en la lección anterior:

Y si además tienen la rama local, esa se borra aparte:

Tres cosas distintas otra vez: la rama del servidor, la referencia remota de cada uno y la rama local de cada uno. La lección siguiente insiste en esa distinción.

Un aviso: borrar una rama en el servidor puede dejar sus commits sin ninguna referencia que los alcance. Si esa rama no estaba fusionada, esos commits quedan a merced del recolector de basura del servidor. Comprueba antes con git log --oneline main..origin/la-rama que no hay nada que perder.

Un detalle que sorprende a casi todo el mundo la primera vez: git push no envía etiquetas.

La etiqueta se ha creado en tu repositorio y ahí se queda. El refspec por defecto solo trata ramas (refs/heads/*), no etiquetas (refs/tags/*).

Las formas de enviarlas:

La diferencia entre las dos últimas importa:

--follow-tags es casi siempre la opción correcta en el uso diario, y se puede dejar configurada:

Y para borrar una etiqueta del servidor, la misma sintaxis de siempre:

Qué son las etiquetas, la diferencia entre ligeras y anotadas, cómo se usan para marcar versiones y cómo encajan en el flujo de publicación es el tema de la lección 05-05: Etiquetando Confirmaciones. Aquí solo nos interesa el transporte: que no viajan solas y con qué opción se envían.

Cerramos con el escenario completo del equipo.

Ana tiene main ya publicada y dos ramas locales pendientes de compartir: documentacion/actualizar-notas y correccion/foco-tras-borrar.

Solo main tiene rama de seguimiento (los corchetes). Las otras dos no existen en el servidor todavía.

Fíjate en la última línea: el seguimiento se ha configurado solo, sin -u. Es push.autoSetupRemote true de la lección 01-06 funcionando.

Ni siquiera ha hecho falta nombrar el remoto ni la rama. Estado final:

Las ramas de Ana están en su disco como referencias remotas, no como ramas locales. Puede examinarlas sin crear nada:

Carla hace lo mismo y decide continuar la corrección de Ana:

Trabaja, confirma y envía:

Este es el ciclo completo cerrado. Fíjate en la forma de esa última línea, distinta de la del primer envío:

• * [new branch] X -> X → se ha creado una rama en el servidor.
• 8a3f7c1..d5e9b2f X -> X → una rama existente ha avanzado de un commit a otro, en fast-forward.

El proyecto que llevaba tres módulos encerrado en un portátil circula ya entre tres máquinas y tres sistemas operativos distintos.

Error 1: "he hecho push y no ven mi cambio". El 90 % de las veces, el cambio no llegó a confirmarse. git push envía commits, no ficheros modificados. Comprueba con git status y git log --oneline -3.

Error 2: responder a un rechazo con --force. El rechazo non-fast-forward significa que el servidor tiene trabajo que tú no tienes. Forzar lo destruye. La respuesta correcta es fetch + integrar + enviar. Ver 09-03.

Error 3: usar --force en lugar de --force-with-lease. El primero no comprueba nada; el segundo se niega si alguien ha enviado algo desde tu último fetch. Cuesta lo mismo escribir uno que otro; haz un alias.

Error 4: hacer fetch justo antes de --force-with-lease. Anula la protección, porque actualiza la referencia con la que Git compara. O miras deliberadamente qué ha llegado, o usas la forma --force-with-lease=rama:hash.

Error 5: forzar una rama compartida. Reescribir main obliga a todo el equipo a resolver un lío que no ha causado. Fuerza solo ramas tuyas de trabajo.

Error 6: creer que git push envía las etiquetas. No lo hace: el refspec por defecto solo cubre refs/heads/*. Usa --follow-tags o configura push.followTags true.

Error 7: usar git push origin :rama sin fijarse. Un espacio de más entre : y el nombre cambia el significado por completo. Usa --delete, que dice lo que hace.

Error 8: borrar una rama del servidor y esperar que desaparezca del repositorio de los demás. Cada persona tiene que hacer git fetch --prune. Configura fetch.prune true en el equipo.

Consejo 1: mira antes de enviar. git log --oneline origin/main..main te enseña exactamente qué commits van a salir. Diez segundos que evitan publicar un wip o un console.log olvidado.

Consejo 2: haz git fetch antes de empezar, no antes de enviar. Así detectas la divergencia cuando todavía es barata de resolver, en vez de descubrirla con el trabajo terminado.

Consejo 3: alias para el forzado seguro.

Consejo 4: revisa qué configura push.default. El valor simple es el correcto. Si trabajas en un equipo con configuraciones antiguas, comprueba que nadie tiene matching.

Consejo 5: --dry-run para ensayar.

Muestra qué haría el envío sin llegar a hacerlo. Útil con refspecs complicados o antes de un borrado.

Monta un servidor bare y un repositorio de trabajo. Después:

1. Confirma tres commits y envía con -u.
2. Muestra el .git/config antes y después, y señala qué líneas ha añadido el -u.
3. Explica la salida completa del push, línea por línea.
4. Confirma otro commit y envía sin -u. ¿Qué cambia en la salida y por qué?
5. Comprueba desde el servidor que las referencias están donde deben, sin clonar.

Con un servidor y dos clones (Ana y Bruno):

1. Los dos parten del mismo commit.
2. Ana confirma y envía.
3. Bruno confirma (sin hacer fetch) e intenta enviar.
4. Captura el mensaje de rechazo y explica exactamente por qué se ha producido, dibujando el grafo.
5. Resuélvelo correctamente sin forzar y demuestra que los commits de los dos siguen en el servidor.
6. Repite el experimento resolviéndolo con --force y demuestra que el commit de Ana ha desaparecido de la rama.

Con un repositorio conectado a un bare, consigue lo siguiente y explica cada comando:

1. Enviar tu rama local funcionalidad/prueba a una rama del servidor llamada experimental/prueba.
2. Enviar el estado de un commit anterior a la punta de tu rama a una rama del servidor llamada revision.
3. Enviar HEAD a main estando en HEAD desacoplado.
4. Borrar experimental/prueba del servidor de las dos formas posibles.
5. Comprobar el resultado con git ls-remote tras cada paso.

Solución 1:

Las líneas nuevas son la sección [branch "main"] con remote y merge. Eso es todo lo que hace -u: establecer la rama de seguimiento.

3. La salida, línea por línea:

• Enumerating objects: 9 — Git ha identificado 9 objetos que enviar: 3 commits + 3 árboles + 3 blobs.
• Delta compression using up to 8 threads — comprime en paralelo, guardando diferencias entre objetos parecidos.
• Writing objects: 100% (9/9), 782 bytes — la subida real: 782 bytes.
• Total 9 (delta 1), reused 0 — de los 9 objetos, 1 se ha guardado como diferencia respecto a otro; ninguno se ha reutilizado porque el servidor estaba vacío.
• To /tmp/ej-push/servidor.git — el destino.
• * [new branch] main -> main — se ha creado la rama main en el servidor. El asterisco y [new branch] marcan la creación.
• branch 'main' set up to track 'origin/main' — el efecto del -u.

Dos diferencias, y las dos tienen explicación:

• Ha bastado git push a secas: el seguimiento ya estaba configurado por el -u anterior, así que Git sabe a qué remoto y a qué rama enviar.
• La línea de resultado ya no dice [new branch] sino 7d2f9a1..4c8e3b6: la rama ya existía y ha avanzado de un commit a otro. Ese rango con dos puntos indica un fast-forward, exactamente la notación que vimos en el fetch.

Además, solo se han enviado 3 objetos nuevos en lugar de los 9 iniciales: el envío es incremental.

Solución 2:

4. Por qué: los dos partieron de 5a1d8f3. Ana creó 9e2f4a7 encima y lo publicó; Bruno creó 7d1f4b8 encima del mismo 5a1d8f3. El grafo:

Para que el envío de Bruno fuera válido, 9e2f4a7 tendría que ser antepasado de 7d1f4b8. No lo es: son ramas hermanas. Si el servidor aceptara la actualización, refs/heads/main pasaría a 7d1f4b8 y 9e2f4a7 dejaría de ser alcanzable: el commit de Ana desaparecería del proyecto. Git lo impide.

Se puede comprobar formalmente:

Si el fichero es el mismo, habrá conflicto (los dos añadieron una línea al final de f.txt). Se resuelve con lo aprendido en 03-05:

Nada se ha perdido. Los dos trabajos conviven, unidos por un commit de fusión con dos padres, exactamente como en el módulo 3.

Ese + y el (forced update) son la marca del desastre:

El commit de Ana ya no está en la rama. Cualquiera que clone ahora no lo verá. Sigue existiendo como objeto suelto en el servidor —y desde luego en el repositorio de Ana—, pero ninguna referencia lo alcanza. Y compara con lo que habría pasado usando la opción segura:

Rechazado. El servidor no estaba donde la foto de Bruno decía, así que la protección ha actuado. Esta es, en una línea, la razón para no escribir --force nunca más.

Solución 3:

El refspec <origen>:<destino> desacopla los dos nombres: a la izquierda lo que envío, a la derecha cómo se llama allí.

Aquí la forma completa refs/heads/revision es necesaria: como la rama de destino no existe todavía, Git no puede deducir si quieres crear una rama o una etiqueta. Con el nombre completo no hay ambigüedad. Y fíjate en que el lado izquierdo es un hash, no un nombre de rama: cualquier expresión que resuelva a un commit vale.

HEAD resuelve al commit en el que estás, aunque no haya ninguna rama apuntándolo. Es la forma de publicar trabajo desde un HEAD desacoplado sin tener que crear una rama local antes.

Las dos hacen lo mismo. La segunda es el refspec con el origen vacío: enviar "nada" a esa referencia la elimina. Es exactamente la misma sintaxis, llevada al extremo.

Quedan main y desde-detached; experimental/prueba y revision han desaparecido. Y un detalle importante: las ramas locales de este repositorio no se han visto afectadas por ninguno de los borrados.

Con esta lección, el trabajo del equipo circula en los dos sentidos. Lo esencial:

• git push envía objetos y pide actualizar una referencia. No envía tu directorio de trabajo, ni tu índice, ni tu configuración, ni tus otras ramas. Solo viaja lo que está dentro de un commit.
• git push -u origin <rama>: el -u escribe la sección [branch "…"] en .git/config y establece la rama de seguimiento. A partir de ahí, git push y git pull a secas funcionan y git status puede informarte del desfase. Con push.autoSetupRemote true (lección 01-06) ni siquiera hace falta.
• El refspec de envío usa la misma sintaxis que el de descarga: origen:destino, izquierda de dónde sale y derecha a dónde va. Permite enviar a una rama con otro nombre, enviar un commit concreto o enviar HEAD.
• push.default simple envía solo la rama actual. El antiguo matching enviaba todas las homónimas y era una fuente de sorpresas: no lo uses.
• El rechazo non-fast-forward ocurre porque el remoto tiene commits que tú no tienes. Si Git aceptara el envío, esos commits dejarían de ser alcanzables y desaparecerían del proyecto. Es una protección, no un fallo. La salida básica es fetch → integrar → enviar; el tratamiento completo, en la lección 09-03.
• --force-with-lease frente a --force: el primero comprueba que el servidor sigue donde tu referencia remota dice y rechaza si alguien ha enviado algo; el segundo sobrescribe sin mirar y puede dejar huérfano el trabajo de otra persona. Usa siempre el primero, y no hagas fetch justo antes (o usa la forma --force-with-lease=rama:hash). Nunca fuerces ramas compartidas.
• Borrar una rama del servidor: git push origin --delete <rama>, o la forma antigua git push origin :<rama> (refspec con origen vacío). Los demás tendrán que hacer git fetch --prune para que desaparezca de sus referencias.
• Las etiquetas no viajan solas: --tags envía todas, --follow-tags solo las anotadas alcanzables desde lo enviado, que suele ser lo que quieres. Las etiquetas, en la lección 05-05.

Ya sabes enviar y recibir. Pero a lo largo de estas lecciones han ido apareciendo mensajes que aún no hemos explicado del todo: "Your branch is ahead of 'origin/main' by 2 commits", "branch 'main' set up to track 'origin/main'", esos corchetes de git branch -vv, y ese git switch que crea una rama local a partir de una remota sin que se lo pidas.

Todo eso apunta al mismo concepto: las ramas de seguimiento. En la lección 04-06: Rastreando Ramas, que cierra el módulo, veremos qué es exactamente el upstream de una rama y dónde vive en .git/config, aclararemos de una vez la diferencia entre main, origin/main y el main del servidor, y desmontaremos cómo calcula Git ese "2 commits por delante". Es la lección que ata todos los cabos del módulo.