git push

Partager et mettre à jour

Mettre à jour les références distantes avec les objets associés

La commande 'git push' envoie le contenu du dépôt local vers un dépôt distant. Elle transfère les commits et les mises à jour de branches (et les tags, quand vous les demandez avec --tags ou --follow-tags) de votre dépôt local vers un dépôt distant, pour que vos modifications soient disponibles pour les autres. Push est la façon de partager votre travail : après avoir committé en local, vous poussez pour vous synchroniser avec l’équipe. Par défaut (push.default=simple), git push ne met à jour que la branche upstream de la branche courante, qui doit exister et porter le même nom, et seulement s’il s’agit d’un fast-forward (la branche distante est un ancêtre de votre branche locale).

Synopsis

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>...]]
[ ] facultatif| ou<arg> valeur à remplacer... répétable--flag option

Options

Cliquez sur une option pour la déplier

Débutant (7)

Le dépôt distant vers lequel pousser. Sans dépôt distant indiqué, Git utilise celui configuré pour la branche courante (son upstream), à défaut 'origin'. Le dépôt peut être une URL ou le nom d’un dépôt distant.

Si nécessaireNomme explicitement le dépôt distant cible ; sinon, c’est celui de l’upstream qui est utilisé

Exemple

git push origin main

Pour chaque branche à jour ou poussée avec succès, ajouter une référence upstream (de suivi). Vous pourrez ensuite utiliser 'git push' et 'git pull' sans arguments pour cette branche.

RecommandéÀ définir une fois sur une nouvelle branche ; push et pull simples fonctionnent ensuite

Exemple

git push -u origin feature-branch

Pousser toutes les branches vers le dépôt distant : chaque branche de refs/heads/ va vers la branche distante du même nom. Depuis Git 2.41, s’écrit aussi --branches. Les tags ne sont pas inclus, et l’option ne se combine pas avec d’autres refspecs.

Si nécessairePousse toutes les branches locales, y compris des expériences que vous vouliez garder privées

Exemple

git push --all origin

Pousser toutes les références sous refs/tags, en plus des refspecs de la ligne de commande. Tous les tags locaux sont poussés vers le dépôt distant.

Si nécessairePousse tous les tags locaux, y compris les égarés ou les légers

Exemple

git push --tags origin

Tout faire sauf envoyer réellement les mises à jour. Montre ce qui serait poussé sans rien modifier sur le dépôt distant.

Si nécessairePrévisualise ce qui serait poussé ; le hook pre-push s’exécute quand même

Exemple

git push --dry-run origin main

Mode verbeux. Donne des détails supplémentaires sur ce qui est poussé et sur la progression de l’opération.

Si nécessairePlus de détails pour déboguer un push

Exemple

git push -v origin main

Masquer toute la sortie, y compris la liste des références mises à jour, sauf en cas d’erreur. La progression n’est pas affichée.

Si nécessairePour les scripts ; sortie seulement en cas d’erreur

Exemple

git push -q origin main

Intermédiaire (6)

Toutes les références listées sont supprimées du dépôt distant. Équivaut à préfixer chaque référence par deux-points (par ex. :branch-name).

Si nécessaireSupprime une branche distante après fusion ; ne peut pas être annulé côté dépôt distant

Exemple

git push --delete origin feature-old

En temps normal, la commande refuse de mettre à jour une référence distante qui n’est pas un ancêtre de la référence locale qui l’écrase. Cette option désactive ces vérifications et autorise les mises à jour non-fast-forward. Le dépôt distant peut alors perdre des commits ; à utiliser avec prudence.

DéconseilléÉcrase le dépôt distant à l’aveugle — utilisez plutôt --force-with-lease

Exemple

git push --force origin feature-branch

Une alternative plus sûre à --force. Cette option autorise le force push mais vérifie d’abord que la référence distante n’a pas été mise à jour par quelqu’un d’autre depuis votre dernier fetch. Si le distant a changé, le push est rejeté, ce qui vous évite d’écraser par accident le travail d’autrui. La vérification se fait par rapport à votre branche de suivi distante, donc un fetch (même en arrière-plan) sans intégration la réinitialise ; associez-la à --force-if-includes.

RecommandéLa façon sûre de pousser un historique réécrit ; refuse si le dépôt distant a bougé

Exemple

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

Transmettre la chaîne donnée au serveur, qui la passe aux hooks pre-receive et post-receive. Peut être répété pour envoyer plusieurs options. Utile pour déclencher des comportements de CI/CD ou transmettre des métadonnées.

Si nécessaireEnvoie des options propres au serveur (par ex. des indications de CI) que votre hébergeur comprend

Exemple

git push -o ci.skip origin main

Supprimer les branches distantes qui n’ont pas d’équivalent local. Ne s’applique qu’aux références correspondant à un refspec à joker (ou à --all) : avec un simple 'git push --prune origin', rien n’est supprimé. Supprime des branches distantes de façon irréversible, prévisualisez donc avec --dry-run.

DéconseilléSupprime les branches distantes absentes en local ; un seul clone périmé peut effacer le travail des collègues

Exemple

git push --all --prune origin

Au lieu de nommer chaque référence à pousser, indique que toutes les références sous refs/ (dont, entre autres, refs/heads/, refs/remotes/ et refs/tags/) sont reproduites en miroir sur le dépôt distant. Les nouvelles références locales sont poussées, celles mises à jour en local sont forcées, et celles supprimées sont retirées. En pratique, cela force chaque référence et supprime les références distantes qui n’existent pas en local.

DéconseilléForce la mise à jour et supprime chaque référence sur le dépôt distant ; seulement pour les sauvegardes ou les migrations

Exemple

git push --mirror origin

Avancé (11)

Sauter le hook pre-push. Par défaut, git push lance le hook pre-push s’il existe. Cette option contourne cette vérification locale (les hooks côté serveur tournent toujours). Avec modération, car les hooks pre-push font souvent respecter des vérifications importantes comme les tests.

DéconseilléSaute vos vérifications pre-push ; seulement quand un hook cassé bloque un push

Exemple

git push --no-verify origin main

Signer avec GPG la demande de push qui met à jour les références côté destinataire. Le serveur peut ainsi vérifier l’identité de la personne qui pousse. Nécessite des clés GPG configurées, et le serveur doit accepter les pushes signés - sinon le push échoue (« the receiving end does not support --signed push »). Peut aussi valoir 'true', 'false' ou 'if-asked' (ne signer que si le serveur le prend en charge).

Si nécessaireSigne le push avec GPG ; échoue sauf si le serveur accepte les push signés

Exemple

git push --signed origin main

Utiliser une transaction atomique côté distant quand c’est possible. Soit toutes les références sont mises à jour, soit, en cas d’erreur, aucune. Si le serveur ne gère pas les pushes atomiques, le push échoue. Utile pour pousser plusieurs branches interdépendantes.

Si nécessaireTout ou rien quand on pousse plusieurs références liées ensemble

Exemple

git push --atomic origin main develop

Pousser toutes les références qui seraient poussées sans cette option, et aussi les tags annotés de refs/tags absents du dépôt distant qui pointent vers des commits accessibles depuis les références poussées. Peut devenir le comportement par défaut avec le réglage push.followTags.

RecommandéPousse les tags de version annotés des commits poussés, en ignorant les tags légers

Exemple

git push --follow-tags origin main

Cette option est une alternative à l’argument <repository>. Si les deux sont donnés, l’argument de la ligne de commande l’emporte. Peut servir dans des scripts ou des configurations pour préciser explicitement le dépôt cible.

Si nécessaireRarement utile ; équivaut à donner l’argument du dépôt

Exemple

git push --repo=origin main

Optimiser le transfert en envoyant un pack « léger », qui enregistre les objets sous forme de deltas par rapport à des objets absents du pack, pour réduire le trafic réseau. C’est le comportement par défaut.

Si nécessaireDéjà le comportement par défaut ; vous n’avez jamais besoin de le taper

Exemple

git push --thin origin main

Désactiver l’optimisation par pack « léger ». Envoie un pack complet sans s’appuyer sur des objets qui existeraient côté destinataire. Peut aider à déboguer des problèmes de transfert.

Si nécessaireSeulement pour dépanner les transferts de packs

Exemple

git push --no-thin origin main

Forcer l’affichage de la progression sur la sortie d’erreur standard, même quand elle n’est pas reliée à un terminal. Utile dans les scripts où vous voulez quand même voir la progression.

Si nécessaireForce l’affichage de la progression dans les logs ou en CI, où stderr n’est pas un terminal

Exemple

git push --progress origin main

Ne forcer la mise à jour que si la pointe de la référence de suivi distante a été intégrée en local. Un force push plus sûr, qui garantit que vous avez vraiment intégré les nouveaux commits distants à votre travail avant de les écraser. N’a d’effet qu’avec --force-with-lease (sans valeur attendue explicite).

RecommandéÀ ajouter à --force-with-lease pour qu’un fetch en arrière-plan ne contourne pas le bail

Exemple

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

Produire une sortie lisible par une machine. La ligne de statut de chaque référence est séparée par des tabulations et envoyée sur stdout au lieu de stderr. Utile pour les scripts qui analysent les résultats du push.

Si nécessaireDes résultats lisibles par une machine, pour les scripts

Exemple

git push --porcelain origin main

Contrôler la gestion des sous-modules pendant le push. Valeurs : 'check' (échoue si les commits des sous-modules ne sont pas poussés), 'on-demand' (pousse les commits des sous-modules si besoin), 'only' (pousse seulement les sous-modules), 'no' (pas de récursion).

Si nécessaireS’assure que les commits des sous-modules sont poussés d’abord

Exemple

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

Choisir la bonne option

L’échelle de sécurité du force push

Quand vous devez écraser l’historique distant, choisissez l’option la plus sûre qui convient à votre situation

CommandeNiveau de risqueVérifie le distantQuand il échoueCas d’usage
git pushSans risque✓ Fast-forward seulementSi le distant a de nouveaux commitsTravail quotidien normal
git push --force-with-lease --force-if-includesForçage le plus sûr✓ Pointe distante dans l’historique localSi vous n’avez pas intégré les modifications distantesAprès un rebase quand d’autres ont pu pousser
git push --force-with-leaseForçage plus sûr✓ Distant inchangé depuis le fetchSi le distant a changé depuis le dernier fetchAprès un rebase sur une branche personnelle
git push --forceDangereux✗ Écrase à l’aveugleJamais (sauf refus du serveur)Seulement quand vous êtes certain, ou seul sur la branche

Ce qui est poussé

Contrôler l’étendue de ce que vous envoyez au dépôt distant

CommandePousseTags inclusUsage typique
git push origin mainUne seule branche✗Pousser une branche précise
git push -u origin branchUne branche + configure le suivi✗Premier push d’une nouvelle branche
git push --allToutes les branches✗Synchroniser toutes les branches locales
git push --tagsTags seulement (pas de branches)✓ Tous les tagsPousser les tags de version
git push --follow-tagsBranche courante✓ Seulement les annotés accessiblesPousser avec les tags de release correspondants
git push --mirrorTout✓ ToutClone exact vers le distant (supprime les références qui n’existent qu’à distance)

Sortie et retours

Adapter la verbosité et le format de sortie à vos besoins

CommandeNiveau de sortieAffiche la progressionLisible par une machineIdéal pour
git pushStandardDans le terminal seulement✗Usage interactif normal
git push --verboseDétaillé✓✗Déboguer un push
git push --quietErreurs seulement✗✗Scripts, pipelines de CI
git push --progressStandard + progression forcée✓ Toujours✗Scripts qui ont besoin de la progression dans les logs
git push --porcelainStructuré✗✓ Séparé par des tabulationsAnalyser les résultats du push dans des scripts

Sécurité et vérification

Vérifications avant push et options de contrôle

CommandeLance les hooksVérifieCrée un commitQuand l’utiliser
git push✓ pre-pushLe distant accepteN/AWorkflow normal
git push --dry-run✓ pre-pushCe qui se passerait✗ Aperçu seulementAvant les pushes importants
git push --atomic✓Toutes les références ou aucuneTout ou rienPousser plusieurs branches ensemble
git push --no-verify✗ Saute le pre-push local (les hooks du serveur tournent toujours)Le distant accepteN/AUrgence quand les hooks vous bloquent
git push --signed✓Signature GPGSigné de façon cryptographiqueDépôts très sécurisés, prouver son identité

Gestion des dépôts distants et des branches

Options pour gérer les références distantes et les relations entre branches

CommandeActionTouche le distantCas d’usage
git push -u origin branchPush + définir l’upstreamAjoute une branchePremier push, configure le suivi
git push origin --delete branchSupprimer une branche distanteRetire une brancheNettoyer les branches fusionnées
git push --pruneSupprimer les branches distantes que vous avez supprimées en local (nécessite --all ou un refspec à joker)Retire des branchesRépercuter les suppressions sur le distant
git push --repo=<url>Pousser vers un dépôt distant précisDépôt distant ciblePousser vers une autre URL distante

Exemples de workflows

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

Ajouter l’URL du dépôt distant

2
git push -u origin main

Pousser la branche main et lui faire suivre origin/main

1
git status

Vérifier que vous êtes sur la bonne branche et avez des commits à pousser

2
git push

Pousser vers la branche upstream suivie

1
git checkout feature

Passer sur votre branche de fonctionnalité

2
git rebase main

Rebaser sur main (réécrit l’historique des commits)

3
git push --force-with-lease

Forcer le push sans risque - échoue si quelqu’un d’autre a poussé

1
git checkout -b feature/new-login

Créer la nouvelle branche et y basculer

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

Faire vos modifications et committer

3
git push -u origin feature/new-login

Pousser et configurer le suivi de l’upstream

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

Supprimer la branche distante

2
git branch -d feature/old-branch

Supprimer aussi la branche locale

1
git push --all origin

Pousser toutes les branches de refs/heads/

2
git push --tags origin

Pousser aussi tous les tags, si vous le souhaitez

Dépannage

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

Cause : La branche distante a des commits que votre branche locale n’a pas. Quelqu’un d’autre a poussé des modifications, ou vous avez fait un rebase/amend de commits déjà poussés.

Récupérez d’abord les modifications distantes avec 'git pull --rebase' ou 'git pull --no-rebase', résolvez les conflits éventuels, puis poussez de nouveau. Ne forcez (de préférence avec '--force-with-lease') que si vous êtes certain que personne d’autre n’utilise la branche.

git pull --rebase && git push

git@github.com: Permission denied (publickey)

Cause : L’authentification SSH a échoué : aucune clé n’est chargée, ou votre clé publique n’est pas ajoutée à votre compte. (Un manque de droit d’écriture donne une autre erreur, « Permission to ... denied ».)

Vérifiez que votre clé SSH est ajoutée à votre compte GitHub/GitLab. Testez avec 'ssh -T git@github.com'. En HTTPS, vérifiez que vous utilisez les bons identifiants.

ssh -T git@github.com

fatal: No configured push destination

Cause : Le dépôt n’a aucun dépôt distant configuré. (Si un dépôt distant existe mais que la branche n’a pas d’upstream, vous obtenez plutôt « The current branch ... has no upstream branch ».)

Ajoutez un dépôt distant avec 'git remote add origin <url>', puis poussez en définissant l’upstream avec 'git push -u origin <branch>'.

git push -u origin main

Your branch is behind 'origin/main'

Cause : La branche distante a des commits plus récents que votre branche locale. Vous devez intégrer ces modifications avant de pousser.

Récupérez les modifications distantes et fusionnez-les ou rebasez-les dans votre branche locale avant de pousser.

git pull origin main && git push

refusing to update checked out branch

Cause : Vous essayez de pousser vers un dépôt non-bare où cette branche est actuellement extraite. Cela pourrait rendre son répertoire de travail incohérent.

Poussez vers un dépôt bare, ou demandez au destinataire d’extraire d’abord une autre branche. Cela arrive en général avec des serveurs personnels, pas avec GitHub/GitLab.

git config receive.denyCurrentBranch updateInstead

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

Cause : Erreur générique aux causes multiples : mises à jour non-fast-forward, échecs de hooks ou problèmes de permissions. Lisez le message d’erreur détaillé au-dessus de cette ligne.

Lisez toute la sortie d’erreur. En général c’est un problème de non-fast-forward (faites d’abord un pull) ou un échec du hook pre-push (corrigez ce que le hook signale).

git pull --rebase && git push

Le hook pre-push a échoué

Cause : Un hook pre-push (tests, lint, etc.) a trouvé des problèmes et a bloqué le push.

Corrigez les problèmes signalés par le hook. Ne le contournez avec '--no-verify' qu’en cas de nécessité absolue et en connaissance de cause.

git push --no-verify

remote: Repository not found

Cause : L’URL du dépôt est incorrecte, le dépôt a été supprimé ou renommé, ou vous n’y avez pas accès.

Vérifiez l’URL du dépôt avec 'git remote -v'. Assurez-vous que le dépôt existe et que vous y avez accès. Mettez l’URL à jour si besoin.

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

Astuces et pièges

Bonnes pratiques

  • ✓Faites toujours un pull avant de pousser : lancez 'git pull' (ou 'git fetch' suivi d’un merge ou d’un rebase) avant de pousser, pour avoir les dernières modifications distantes et éviter les pushes rejetés.
  • ✓Utilisez --force-with-lease plutôt que --force : si vous devez forcer, --force-with-lease est plus sûr car il échoue si quelqu’un d’autre a poussé depuis votre dernier fetch (ajoutez --force-if-includes pour plus de sécurité).
  • ✓Définissez l’upstream au premier push : utilisez 'git push -u origin branch-name' pour une nouvelle branche afin de configurer le suivi. Ensuite, un simple 'git push' suffit.
  • ✓Ne forcez jamais un push sur des branches partagées : forcer sur main, master ou develop peut détruire le travail des autres. Utilisez des commits de revert plutôt que de réécrire l’historique.
  • ✓Utilisez des règles de protection de branches : configurez votre dépôt pour interdire les force pushes sur les branches importantes et exiger des relectures de pull requests.
  • ✓Poussez souvent pour sauvegarder votre travail : pousser régulièrement vos branches de fonctionnalité sert de sauvegarde et montre votre avancement aux autres.
  • ✓Vérifiez avant de pousser : utilisez 'git push --dry-run' pour voir ce qui serait poussé sans rien pousser. Idéal pour revérifier.
  • ✓Nettoyez les branches distantes : supprimez les branches de fonctionnalité fusionnées avec 'git push origin --delete branch-name' pour garder le dépôt distant en ordre.
  • ✓Utilisez les pushes atomiques pour des modifications liées : quand vous poussez plusieurs branches qui dépendent les unes des autres, utilisez '--atomic' pour que tout réussisse ou que rien ne passe.
  • ✓Signez les pushes importants : pour les dépôts critiques, utilisez '--signed' pour signer vos pushes avec GPG et permettre leur vérification (le serveur doit accepter les pushes signés, sinon le push échoue).

Erreurs fréquentes

  • ✗Pousser sans avoir fait de pull : si le dépôt distant a de nouveaux commits, votre push sera rejeté. Faites toujours 'git pull' (ou fetch, puis merge/rebase) d’abord pour intégrer les modifications distantes.
  • ✗Utiliser --force sur des branches partagées : forcer réécrit l’historique et peut détruire le travail des autres. Utilisez plutôt --force-with-lease, ou mieux, évitez complètement de forcer sur les branches partagées.
  • ✗Oublier de définir l’upstream avec -u : au premier push d’une nouvelle branche, utilisez 'git push -u origin branch-name' pour configurer le suivi. Sinon, il faudra préciser le dépôt distant et la branche à chaque fois.
  • ✗Pousser vers la mauvaise branche : vérifiez votre branche courante avec 'git branch' avant de pousser. Utilisez une syntaxe explicite comme 'git push origin feature:feature' pour être sûr.
  • ✗Ne pas comprendre les pushes rejetés : les erreurs « non-fast-forward » signifient que le dépôt distant a des commits que vous n’avez pas en local. Faites un pull et un merge/rebase avant de pousser - ne forcez pas simplement.

FAQ

A:

'git push' envoie vos commits locaux vers un dépôt distant pour que vos modifications soient disponibles pour les autres. 'git pull' télécharge les commits d’un dépôt distant et les fusionne dans votre branche locale. Push envoie des données ; pull en rapporte.

A:

On ne peut pas vraiment « annuler » un push, puisque c’est de l’historique partagé. Pour revenir en arrière sans risque, utilisez 'git revert HEAD' pour créer un nouveau commit qui annule les modifications, puis poussez de nouveau. Évitez 'git reset' + force push sur des branches partagées : cela réécrit un historique que d’autres ont peut-être déjà récupéré.

A:

L’option -u crée une relation de suivi entre votre branche locale et la branche distante. Après 'git push -u origin feature', vous pouvez simplement utiliser 'git push' et 'git pull' sans préciser le dépôt distant et la branche à chaque fois.

A:

Le force push (--force) ne doit servir que sur des branches où vous êtes seul à contribuer, comme une branche de fonctionnalité personnelle après un rebase. Ne forcez jamais sur des branches partagées comme main ou develop. Si vous devez le faire, utilisez --force-with-lease par sécurité.

A:

Utilisez la syntaxe refspec : 'git push origin local-branch:remote-branch'. Par exemple, 'git push origin feature:experiment' pousse votre branche locale 'feature' vers une branche distante nommée 'experiment'.

A:

En général, parce que le dépôt distant a des commits que vous n’avez pas en local (non-fast-forward). Lancez 'git pull' pour récupérer et fusionner ces modifications, résolvez les conflits éventuels, puis poussez de nouveau. Ne forcez pas sauf si vous êtes certain que c’est sans danger.

A:

Utilisez 'git push --all origin' pour pousser toutes les branches locales vers le dépôt distant. Les tags demandent une commande séparée, car '--all' et '--tags' ne peuvent pas être combinés : 'git push --tags origin'.

A:

'--force' écrase aveuglément la branche distante, quel que soit son état. '--force-with-lease' n’écrase que si le distant n’a pas changé depuis votre dernier fetch - il échoue si quelqu’un d’autre a poussé, ce qui protège son travail. Attention : un fetch (même un fetch en arrière-plan d’un IDE) rafraîchit cette vérification, donc ajoutez --force-if-includes pour exiger aussi que vous ayez intégré ce que vous avez récupéré.

A:

Utilisez 'git push origin --delete branch-name' ou la forme courte 'git push origin :branch-name'. Les deux retirent la branche du dépôt distant.

A:

Un simple 'git push' ne fonctionne que si la branche courante a une branche upstream configurée. Pour les nouvelles branches, il faut d’abord 'git push -u origin branch-name'. Vérifiez les relations de suivi avec 'git branch -vv'.