git push

Compartir y actualizar

Actualizar las referencias remotas junto con sus objetos

El comando 'git push' sube el contenido del repositorio local a un repositorio remoto. Transfiere commits y actualizaciones de ramas (y etiquetas, cuando las pides con --tags o --follow-tags) de tu repositorio local a un remoto, para que tus cambios estén disponibles para los demás. Push es la forma de compartir tu trabajo: tras hacer commit en local, haces push para sincronizarte con el equipo. Por defecto (push.default=simple), git push solo actualiza la rama upstream de la rama actual, que debe existir y llamarse igual, y solo si es un fast-forward (es decir, si la rama remota es un ancestro de tu rama local).

Sinopsis

git push [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose] [-u | --set-upstream] [-o <string>] [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]] [--no-verify] [<repository> [<refspec>...]]
[ ] opcional| o<arg> valor a sustituir... repetible--flag opción

Opciones

Haz clic en una opción para desplegarla

Principiante (7)

El repositorio remoto al que subir. Si no se indica, Git usa el remoto configurado para la rama actual (su upstream) y, si no hay, 'origin'. Puede ser una URL o el nombre de un remoto.

Cuando haga faltaIndica explícitamente el remoto de destino; si no, se usa el del upstream

Ejemplo

git push origin main

Por cada rama que esté al día o se suba correctamente, añadir la referencia upstream (de seguimiento). Así podrás usar 'git push' y 'git pull' sin argumentos para esa rama en el futuro.

RecomendadoSe define una vez en una rama nueva; luego push y pull a secas funcionan sin más

Ejemplo

git push -u origin feature-branch

Subir todas las ramas al remoto: cada rama de refs/heads/ va a la rama remota con el mismo nombre. Desde Git 2.41 también se escribe --branches. No incluye etiquetas y no se puede combinar con otros refspecs.

Cuando haga faltaSube todas las ramas locales, incluidos experimentos que querías mantener privados

Ejemplo

git push --all origin

Subir todas las referencias de refs/tags, además de los refspecs de la línea de comandos. Se suben al remoto todas las etiquetas locales.

Cuando haga faltaSube todas las etiquetas locales, incluidas las sueltas o ligeras

Ejemplo

git push --tags origin

Hacerlo todo salvo enviar de verdad las actualizaciones. Muestra lo que se subiría sin cambiar nada en el remoto.

Cuando haga faltaPrevisualiza lo que se subiría; el hook pre-push se ejecuta igualmente

Ejemplo

git push --dry-run origin main

Modo detallado. Da información adicional sobre lo que se sube y el progreso de la operación.

Cuando haga faltaMás detalle al depurar un push

Ejemplo

git push -v origin main

Silenciar toda la salida, incluida la lista de referencias actualizadas, salvo que haya un error. No se muestra el progreso.

Cuando haga faltaPara scripts; solo muestra salida si hay errores

Ejemplo

git push -q origin main

Intermedio (6)

Todas las referencias indicadas se borran del repositorio remoto. Es lo mismo que poner dos puntos delante de cada referencia (p. ej. :branch-name).

Cuando haga faltaElimina una rama remota tras fusionarla; no se puede deshacer desde el remoto

Ejemplo

git push --delete origin feature-old

Normalmente, el comando se niega a actualizar una referencia remota que no es ancestro de la referencia local que la sobrescribe. Esta opción desactiva esas comprobaciones y permite actualizaciones non-fast-forward. El remoto puede perder commits; úsala con cuidado.

No recomendadoSobrescribe el remoto a ciegas; usa mejor --force-with-lease

Ejemplo

git push --force origin feature-branch

Una alternativa más segura a --force. Permite el force push, pero antes comprueba que nadie más haya actualizado la referencia remota desde tu último fetch. Si el remoto cambió, el push se rechaza y evitas sobrescribir sin querer el trabajo de otra persona. La comprobación se hace contra tu rama de seguimiento remoto, así que un fetch (incluso en segundo plano) sin integrar la reinicia; combínala con --force-if-includes.

RecomendadoLa forma segura de subir un historial reescrito; se niega si el remoto se movió

Ejemplo

git push --force-with-lease origin feature-branch

Enviar la cadena indicada al servidor, que la pasa a los hooks pre-receive y post-receive. Puede repetirse para enviar varias opciones. Útil para activar comportamientos de CI/CD o pasar metadatos.

Cuando haga faltaEnvía opciones propias del servidor (p. ej. indicaciones para la CI) que tu servicio de alojamiento entiende

Ejemplo

git push -o ci.skip origin main

Borrar las ramas remotas que no tienen equivalente local. Solo afecta a las referencias que coinciden con un refspec con comodín (o --all): con un simple 'git push --prune origin' no se borra nada. Borra ramas remotas de forma irreversible, así que míralo antes con --dry-run.

No recomendadoBorra ramas remotas que faltan en local; un solo clon desactualizado puede borrar trabajo de tus compañeros

Ejemplo

git push --all --prune origin

En lugar de nombrar cada referencia que subir, indica que todas las referencias de refs/ (entre otras, refs/heads/, refs/remotes/ y refs/tags/) se replican en espejo en el remoto. Las referencias locales nuevas se suben, las actualizadas en local se fuerzan y las borradas se eliminan. En la práctica, fuerza todas las referencias y borra las remotas que no existen en local.

No recomendadoFuerza la actualización y borra todas las referencias del remoto; solo para copias de seguridad o migraciones

Ejemplo

git push --mirror origin

Avanzado (11)

Saltarse el hook pre-push. Por defecto, git push ejecuta el hook pre-push si existe. Esta opción se salta esa comprobación local (los hooks del servidor se siguen ejecutando). Con moderación, porque los hooks pre-push suelen imponer comprobaciones importantes, como pasar los tests.

No recomendadoSe salta tus comprobaciones pre-push; solo cuando un hook roto bloquea un push

Ejemplo

git push --no-verify origin main

Firmar con GPG la petición de push que actualiza las referencias en el receptor. Así el servidor puede verificar la identidad de quien sube. Requiere claves GPG configuradas y que el servidor admita push firmados; si no, el push falla («the receiving end does not support --signed push»). También admite 'true', 'false' o 'if-asked' (firmar solo si el servidor lo admite).

Cuando haga faltaFirma el push con GPG; falla salvo que el servidor admita push firmados

Ejemplo

git push --signed origin main

Usar una transacción atómica en el remoto cuando esté disponible. O se actualizan todas las referencias o, si hay un error, ninguna. Si el servidor no admite push atómicos, el push falla. Útil al subir varias ramas interdependientes.

Cuando haga faltaTodo o nada al subir juntas varias referencias relacionadas

Ejemplo

git push --atomic origin main develop

Subir todas las referencias que se subirían sin esta opción y, además, las etiquetas anotadas de refs/tags que faltan en el remoto y apuntan a commits alcanzables desde las referencias que se suben. Puede fijarse como comportamiento por defecto con la opción push.followTags.

RecomendadoSube las etiquetas de versión anotadas de los commits subidos, omitiendo las ligeras

Ejemplo

git push --follow-tags origin main

Esta opción es una alternativa al argumento <repository>. Si se indican los dos, manda el argumento de la línea de comandos. Puede usarse en scripts o configuraciones para indicar de forma explícita el repositorio de destino.

Cuando haga faltaCasi nunca hace falta; es lo mismo que dar el argumento del repositorio

Ejemplo

git push --repo=origin main

Optimizar la transferencia enviando un pack «ligero», que guarda los objetos como deltas respecto a objetos no incluidos en el pack para reducir el tráfico de red. Es el comportamiento por defecto.

Cuando haga faltaYa es lo predeterminado; nunca necesitas escribirlo

Ejemplo

git push --thin origin main

Desactivar la optimización de pack «ligero». Envía un pack completo sin apoyarse en objetos que podrían existir en el receptor. Puede servir para depurar problemas de transferencia.

Cuando haga faltaSolo para solucionar problemas en la transferencia de packs

Ejemplo

git push --no-thin origin main

Forzar que el progreso se muestre en la salida de error estándar aunque no esté conectada a una terminal. Útil en scripts donde aun así quieres ver el progreso.

Cuando haga faltaFuerza la salida de progreso en logs o CI, donde stderr no es una terminal

Ejemplo

git push --progress origin main

Forzar la actualización solo si la punta de la referencia de seguimiento remoto se ha integrado en local. Un force push más seguro que garantiza que de verdad has integrado los commits remotos nuevos antes de sobrescribirlos. Solo tiene efecto junto con --force-with-lease (sin valor esperado explícito).

RecomendadoAñádelo a --force-with-lease para que un fetch en segundo plano no se salte la garantía

Ejemplo

git push --force-with-lease --force-if-includes origin feature

Generar una salida legible por máquinas. La línea de estado de cada referencia va separada por tabuladores y se envía a stdout en lugar de stderr. Útil para scripts que analizan los resultados del push.

Cuando haga faltaResultados legibles por máquinas para scripts

Ejemplo

git push --porcelain origin main

Controlar cómo se tratan los submódulos durante el push. Valores: 'check' (falla si los commits de los submódulos no están subidos), 'on-demand' (sube los commits de los submódulos si hace falta), 'only' (solo sube los submódulos), 'no' (sin recursión).

Cuando haga faltaSe asegura de que los commits de los submódulos se suban primero

Ejemplo

git push --recurse-submodules=on-demand origin main

Elegir la opción adecuada

La escalera de seguridad del force push

Cuando tengas que sobrescribir el historial remoto, elige la opción más segura que sirva para tu caso

ComandoNivel de riesgoComprueba el remotoCuándo fallaCaso de uso
git pushSeguro✓ Solo fast-forwardSi el remoto tiene commits nuevosFlujo diario normal
git push --force-with-lease --force-if-includesEl forzado más seguro✓ Punta remota en el historial localSi no has integrado los cambios remotosTras un rebase cuando otros pueden haber subido
git push --force-with-leaseForzado más seguro✓ Remoto sin cambios desde el fetchSi el remoto cambió desde el último fetchTras un rebase en una rama personal
git push --forcePeligroso✗ Sobrescribe a ciegasNunca (salvo que el servidor lo rechace)Solo si estás seguro, o en una rama solo tuya

Qué se sube

Controlar el alcance de lo que envías al remoto

ComandoSubeIncluye etiquetasUso típico
git push origin mainUna sola rama✗Subir una rama concreta
git push -u origin branchUna rama + configura el seguimiento✗Primer push de una rama nueva
git push --allTodas las ramas✗Sincronizar todas las ramas locales
git push --tagsSolo etiquetas (sin ramas)✓ Todas las etiquetasSubir las etiquetas de versión
git push --follow-tagsRama actual✓ Solo las anotadas alcanzablesSubir con las etiquetas de release correspondientes
git push --mirrorTodo✓ TodoClon exacto en el remoto (borra las referencias que solo existen en el remoto)

Salida y respuesta

Ajustar el nivel de detalle y el formato de salida a lo que necesites

ComandoNivel de salidaMuestra el progresoLegible por máquinasIdeal para
git pushNormalSolo en la terminal✗Uso interactivo normal
git push --verboseDetallado✓✗Depurar problemas de push
git push --quietSolo errores✗✗Scripts, pipelines de CI
git push --progressNormal + progreso forzado✓ Siempre✗Scripts que necesitan el progreso en los logs
git push --porcelainEstructurado✗✓ Separado por tabuladoresAnalizar los resultados del push en scripts

Seguridad y verificación

Comprobaciones previas al push y opciones de verificación

ComandoEjecuta hooksVerificaCrea commitCuándo usarla
git push✓ pre-pushLo acepta el remotoN/AFlujo normal
git push --dry-run✓ pre-pushQué pasaría✗ Solo vista previaAntes de push importantes
git push --atomic✓Todas las referencias o ningunaTodo o nadaSubir varias ramas juntas
git push --no-verify✗ Salta el pre-push local (los hooks del servidor se siguen ejecutando)Lo acepta el remotoN/AEmergencia cuando los hooks te bloquean
git push --signed✓Firma GPGFirmado criptográficamenteRepositorios de alta seguridad, demostrar identidad

Gestión de remotos y ramas

Opciones para gestionar referencias remotas y relaciones entre ramas

ComandoAcciónAfecta al remotoCaso de uso
git push -u origin branchPush + fijar el upstreamAñade una ramaPrimer push, configura el seguimiento
git push origin --delete branchBorrar una rama remotaElimina una ramaLimpiar ramas ya integradas
git push --pruneBorrar las ramas remotas que borraste en local (requiere --all o un refspec con comodín)Elimina ramasLlevar los borrados al remoto
git push --repo=<url>Subir a un remoto concretoRemoto de destinoSubir a otra URL remota

Ejemplos de flujos de trabajo

1
git remote add origin https://github.com/user/repo.git

Añadir la URL del repositorio remoto

2
git push -u origin main

Subir la rama main y hacer que siga a origin/main

1
git status

Comprobar que estás en la rama correcta y tienes commits para subir

2
git push

Subir a la rama upstream que se sigue

1
git checkout feature

Cambiarse a tu rama de funcionalidad

2
git rebase main

Rebase sobre main (reescribe el historial de commits)

3
git push --force-with-lease

Forzar el push con seguridad: falla si otra persona subió algo

1
git checkout -b feature/new-login

Crear la rama nueva y cambiarse a ella

2
git add . && git commit -m "Add new login"

Hacer tus cambios y el commit

3
git push -u origin feature/new-login

Subir y configurar el seguimiento del upstream

1
git push origin --delete feature/old-branch

Borrar la rama remota

2
git branch -d feature/old-branch

Borrar también la rama local

1
git push --all origin

Subir todas las ramas de refs/heads/

2
git push --tags origin

Opcionalmente, subir también todas las etiquetas

Solución de problemas

! [rejected] main -> main (fetch first) / (non-fast-forward)

Causa: La rama remota tiene commits que tu rama local no tiene. Otra persona subió cambios, o hiciste rebase/amend de commits que ya estaban subidos.

Trae antes los cambios remotos con 'git pull --rebase' o 'git pull --no-rebase', resuelve los conflictos si los hay y vuelve a subir. Fuerza (mejor con '--force-with-lease') solo si estás seguro de que nadie más usa la rama.

git pull --rebase && git push

git@github.com: Permission denied (publickey)

Causa: Falló la autenticación SSH: no hay ninguna clave cargada o tu clave pública no está añadida a tu cuenta. (La falta de permiso de escritura da otro error, «Permission to ... denied».)

Comprueba que tu clave SSH está añadida a tu cuenta de GitHub/GitLab. Verifícalo con 'ssh -T git@github.com'. Con HTTPS, asegúrate de usar las credenciales correctas.

ssh -T git@github.com

fatal: No configured push destination

Causa: El repositorio no tiene ningún remoto configurado. (Si existe un remoto pero la rama no tiene upstream, verás «The current branch ... has no upstream branch».)

Añade un remoto con 'git remote add origin <url>' y luego sube fijando el upstream con 'git push -u origin <branch>'.

git push -u origin main

Your branch is behind 'origin/main'

Causa: La rama remota tiene commits más recientes que tu rama local. Tienes que integrar esos cambios antes de subir.

Descarga los cambios remotos e intégralos con merge o rebase en tu rama local antes de subir.

git pull origin main && git push

refusing to update checked out branch

Causa: Intentas subir a un repositorio no bare donde esa rama está en checkout. Eso podría dejar su directorio de trabajo en un estado incoherente.

Sube a un repositorio bare, o pide al receptor que antes haga checkout de otra rama. Suele pasar con servidores personales, no con GitHub/GitLab.

git config receive.denyCurrentBranch updateInstead

error: failed to push some refs to '<remote-url>'

Causa: Error genérico con varias causas posibles: actualizaciones non-fast-forward, fallos de hooks o problemas de permisos. Mira el mensaje de error detallado encima de esta línea.

Lee toda la salida de error. Normalmente es un problema de non-fast-forward (haz pull antes) o un fallo del hook pre-push (arregla lo que indique el hook).

git pull --rebase && git push

Falló el hook pre-push

Causa: Un hook pre-push (tests, lint, etc.) encontró problemas y bloqueó el push.

Arregla los problemas que indica el hook. Sáltatelo con '--no-verify' solo si es absolutamente necesario y entiendes las consecuencias.

git push --no-verify

remote: Repository not found

Causa: La URL del repositorio es incorrecta, el repositorio se borró o se renombró, o no tienes acceso a él.

Comprueba la URL del repositorio con 'git remote -v'. Verifica que el repositorio existe y que tienes acceso. Actualiza la URL si hace falta.

git remote set-url origin https://github.com/user/correct-repo.git

Consejos y trampas

Buenas prácticas

  • ✓Haz siempre pull antes del push: ejecuta 'git pull' (o 'git fetch' seguido de merge o rebase) antes de subir para tener los últimos cambios remotos y evitar pushes rechazados.
  • ✓Usa --force-with-lease en lugar de --force: si tienes que forzar, --force-with-lease es más seguro porque falla si otra persona subió al remoto desde tu último fetch (añade --force-if-includes para más seguridad).
  • ✓Fija el upstream en el primer push: usa 'git push -u origin branch-name' al subir una rama nueva para configurar el seguimiento. Después te basta con 'git push'.
  • ✓Nunca hagas force push a ramas compartidas: forzar en main, master o develop puede destruir el trabajo de otros. Usa commits de revert en lugar de reescribir el historial.
  • ✓Usa reglas de protección de ramas: configura tu repositorio para impedir los force push en ramas importantes y exigir revisiones de pull requests.
  • ✓Sube a menudo para respaldar tu trabajo: los push frecuentes de las ramas de funcionalidad sirven de copia de seguridad y dejan ver tu avance.
  • ✓Comprueba antes de subir: usa 'git push --dry-run' para ver qué se subiría sin subir nada. Ideal para verificarlo dos veces.
  • ✓Limpia las ramas remotas: borra las ramas de funcionalidad ya integradas con 'git push origin --delete branch-name' para mantener ordenado el remoto.
  • ✓Usa push atómicos para cambios relacionados: al subir varias ramas que dependen entre sí, usa '--atomic' para que o se suban todas o ninguna.
  • ✓Firma los push importantes: en repositorios críticos, usa '--signed' para firmar tus push con GPG y poder verificarlos (el servidor debe admitir push firmados; si no, el push falla).

Errores comunes

  • ✗Hacer push sin hacer pull antes: si el remoto tiene commits nuevos, tu push será rechazado. Haz siempre 'git pull' (o fetch y luego merge/rebase) primero para incorporar los cambios remotos.
  • ✗Usar --force en ramas compartidas: forzar reescribe el historial y puede destruir el trabajo de otros. Usa --force-with-lease o, mejor aún, evita por completo el force push en ramas compartidas.
  • ✗Olvidar fijar el upstream con -u: en el primer push de una rama nueva, usa 'git push -u origin branch-name' para configurar el seguimiento. Si no, tendrás que indicar el remoto y la rama cada vez.
  • ✗Subir a la rama equivocada: comprueba tu rama actual con 'git branch' antes del push. Usa una sintaxis explícita como 'git push origin feature:feature' para ir sobre seguro.
  • ✗No entender los push rechazados: los errores «non-fast-forward» significan que el remoto tiene commits que no tienes en local. Haz pull y merge/rebase antes de subir; no fuerces sin más.

Preguntas frecuentes

A:

'git push' sube tus commits locales a un repositorio remoto para que tus cambios estén disponibles para los demás. 'git pull' descarga commits de un remoto y los integra en tu rama local. Push envía datos; pull los trae.

A:

Un push no se puede «deshacer» de verdad, porque ya es historial compartido. Para revertirlo con seguridad, usa 'git revert HEAD' para crear un commit nuevo que deshaga los cambios y vuelve a subir. Evita 'git reset' + force push en ramas compartidas, porque reescribe un historial que otros quizá ya descargaron.

A:

La opción -u crea una relación de seguimiento entre tu rama local y la rama remota. Tras 'git push -u origin feature', puedes usar simplemente 'git push' y 'git pull' sin indicar el remoto y la rama cada vez.

A:

El force push (--force) solo debe usarse en ramas donde eres la única persona que contribuye, como tus ramas de funcionalidad tras un rebase. Nunca fuerces en ramas compartidas como main o develop. Si no queda otra, usa --force-with-lease por seguridad.

A:

Usa la sintaxis refspec: 'git push origin local-branch:remote-branch'. Por ejemplo, 'git push origin feature:experiment' sube tu rama local 'feature' a una rama remota llamada 'experiment'.

A:

Normalmente porque el remoto tiene commits que no tienes en local (non-fast-forward). Ejecuta 'git pull' para traer e integrar esos cambios, resuelve los conflictos si los hay y vuelve a subir. No fuerces salvo que estés seguro de que no hay riesgo.

A:

Usa 'git push --all origin' para subir todas las ramas locales al remoto. Las etiquetas necesitan otro comando, porque '--all' y '--tags' no se pueden combinar: 'git push --tags origin'.

A:

'--force' sobrescribe a ciegas la rama remota sin mirar su estado. '--force-with-lease' solo sobrescribe si el remoto no ha cambiado desde tu último fetch: falla si otra persona subió algo, y así protege su trabajo. Ojo: un fetch (incluso uno en segundo plano de tu IDE) refresca esa comprobación, así que añade --force-if-includes para exigir además que hayas integrado lo que descargaste.

A:

Usa 'git push origin --delete branch-name' o la forma corta 'git push origin :branch-name'. Ambas eliminan la rama del repositorio remoto.

A:

'git push' a secas solo funciona si la rama actual tiene configurada una rama upstream. Para ramas nuevas, primero necesitas 'git push -u origin branch-name'. Revisa las relaciones de seguimiento con 'git branch -vv'.