git push

Compartilhar e atualizar

Atualizar refs remotas junto com os objetos associados

O comando 'git push' envia o conteúdo do repositório local para um repositório remoto. Ele transfere commits e atualizações de branches (e tags, quando você pede com --tags ou --follow-tags) do seu repositório local para um remoto, deixando as suas mudanças disponíveis para os outros. O push é como você compartilha o trabalho - depois de fazer commit localmente, você envia para sincronizar com a equipe. Por padrão (push.default=simple), git push só atualiza a branch upstream da branch atual, que precisa existir e ter o mesmo nome, e só se for um fast-forward (ou seja, se a branch remota for ancestral da sua branch local).

Sinopse

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| ou<arg> valor a substituir... repetível--flag opção

Opções

Clique em uma opção para expandir

Iniciante (7)

O repositório remoto para onde enviar. Se nenhum for indicado, o Git usa o remoto configurado para a branch atual (o upstream dela) e, na falta dele, 'origin'. Pode ser uma URL ou o nome de um remoto.

Quando necessárioInforma explicitamente o remoto de destino; senão, é usado o remoto do upstream

Exemplo

git push origin main

Para cada branch atualizada ou enviada com sucesso, adicionar a referência de upstream (rastreamento). Assim você pode usar 'git push' e 'git pull' sem argumentos nessa branch daqui em diante.

RecomendadoDefina uma vez em uma branch nova; depois push e pull simples funcionam

Exemplo

git push -u origin feature-branch

Enviar todas as branches para o remoto: cada branch de refs/heads/ vai para a branch remota de mesmo nome. Desde o Git 2.41 também se escreve --branches. As tags não entram, e a opção não pode ser combinada com outros refspecs.

Quando necessárioEnvia todas as branches locais, inclusive experimentos que você queria manter privados

Exemplo

git push --all origin

Enviar todas as refs em refs/tags, além dos refspecs da linha de comando. Todas as tags locais vão para o remoto.

Quando necessárioEnvia todas as tags locais, inclusive as soltas ou leves

Exemplo

git push --tags origin

Fazer tudo, menos enviar de fato as atualizações. Mostra o que seria enviado sem mudar nada no remoto.

Quando necessárioPré-visualiza o que seria enviado; o hook pre-push roda mesmo assim

Exemplo

git push --dry-run origin main

Modo detalhado. Mostra informações extras sobre o que está sendo enviado e o progresso da operação.

Quando necessárioMais detalhes para depurar um push

Exemplo

git push -v origin main

Silenciar toda a saída, incluindo a lista de refs atualizadas, a não ser que ocorra um erro. O progresso não é mostrado.

Quando necessárioPara scripts; saída só em caso de erro

Exemplo

git push -q origin main

Intermediário (6)

Todas as refs listadas são excluídas do repositório remoto. É o mesmo que prefixar cada ref com dois-pontos (por ex. :branch-name).

Quando necessárioRemove uma branch remota depois do merge; não dá para desfazer no remoto

Exemplo

git push --delete origin feature-old

Normalmente, o comando se recusa a atualizar uma ref remota que não é ancestral da ref local usada para sobrescrevê-la. Esta opção desativa essas verificações e permite atualizações non-fast-forward. O repositório remoto pode perder commits; use com cuidado.

Não recomendadoSobrescreve o remoto às cegas — use --force-with-lease em vez disso

Exemplo

git push --force origin feature-branch

Uma alternativa mais segura ao --force. Esta opção permite o force push, mas antes confere se a ref remota não foi atualizada por outra pessoa desde o seu último fetch. Se o remoto mudou, o push é rejeitado, evitando que você sobrescreva sem querer o trabalho de alguém. A verificação compara com a sua branch de rastreamento remoto, então um fetch (até em segundo plano) sem integração a reinicia; combine com --force-if-includes.

RecomendadoO jeito seguro de enviar histórico reescrito; recusa se o remoto se moveu

Exemplo

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

Enviar a string indicada para o servidor, que a repassa aos hooks pre-receive e post-receive. Pode ser repetido para enviar várias opções. Útil para disparar comportamentos de CI/CD ou passar metadados.

Quando necessárioEnvia opções específicas do servidor (por ex. dicas para a CI) que o seu serviço de hospedagem entende

Exemplo

git push -o ci.skip origin main

Excluir branches remotas que não têm correspondente local. Só vale para refs que casam com um refspec curinga (ou --all): com um simples 'git push --prune origin', nada é excluído. Exclui branches remotas de forma irreversível, então pré-visualize com --dry-run.

Não recomendadoExclui branches remotas que faltam localmente; um só clone desatualizado pode apagar o trabalho dos colegas

Exemplo

git push --all --prune origin

Em vez de nomear cada ref a enviar, indica que todas as refs em refs/ (incluindo, entre outras, refs/heads/, refs/remotes/ e refs/tags/) sejam espelhadas no repositório remoto. Refs locais novas são enviadas, as atualizadas localmente são forçadas e as excluídas são removidas. Na prática, força cada ref e exclui as refs remotas que não existem localmente.

Não recomendadoForça a atualização e exclui cada ref do remoto; só para backups ou migrações

Exemplo

git push --mirror origin

Avançado (11)

Pular o hook pre-push. Por padrão, o git push roda o hook pre-push se ele existir. Esta opção pula essa verificação local (os hooks do servidor continuam rodando). Use com moderação, pois os hooks pre-push costumam garantir verificações importantes, como rodar os testes.

Não recomendadoPula as suas verificações de pre-push; só quando um hook quebrado bloqueia o push

Exemplo

git push --no-verify origin main

Assinar com GPG o pedido de push que atualiza as refs no destino. Assim o servidor pode verificar a identidade de quem envia. Exige chaves GPG configuradas, e o servidor precisa aceitar pushes assinados - senão o push falha (“the receiving end does not support --signed push”). Também aceita 'true', 'false' ou 'if-asked' (assina só se o servidor suportar).

Quando necessárioAssina o push com GPG; falha a menos que o servidor suporte pushes assinados

Exemplo

git push --signed origin main

Usar uma transação atômica no lado remoto quando disponível. Ou todas as refs são atualizadas, ou, em caso de erro, nenhuma é. Se o servidor não suportar pushes atômicos, o push falha. Útil ao enviar várias branches interdependentes.

Quando necessárioTudo ou nada ao enviar juntas várias refs relacionadas

Exemplo

git push --atomic origin main develop

Enviar todas as refs que seriam enviadas sem esta opção e também as tags anotadas de refs/tags que faltam no remoto e apontam para commits alcançáveis a partir das refs enviadas. Pode virar o padrão com a configuração push.followTags.

RecomendadoEnvia tags de versão anotadas dos commits enviados, pulando as leves

Exemplo

git push --follow-tags origin main

Esta opção é uma alternativa ao argumento <repository>. Se os dois forem indicados, vale o argumento da linha de comando. Pode ser usada em scripts ou configurações para indicar explicitamente o repositório de destino.

Quando necessárioRaramente necessário; o mesmo que passar o argumento do repositório

Exemplo

git push --repo=origin main

Otimizar a transferência enviando um pack “leve”, que guarda os objetos como deltas em relação a objetos fora do pack, reduzindo o tráfego de rede. É o comportamento padrão.

Quando necessárioJá é o padrão; você nunca precisa digitá-lo

Exemplo

git push --thin origin main

Desativar a otimização de pack “leve”. Envia um pack completo sem depender de objetos que possam existir no destino. Pode ajudar a depurar problemas de transferência.

Quando necessárioSó para resolver problemas na transferência de packs

Exemplo

git push --no-thin origin main

Forçar a exibição do progresso na saída de erro padrão, mesmo que ela não esteja ligada a um terminal. Útil em scripts em que você ainda quer ver o progresso do push.

Quando necessárioForça a saída de progresso em logs ou CI, onde o stderr não é um terminal

Exemplo

git push --progress origin main

Só forçar a atualização se a ponta da ref de rastreamento remoto já tiver sido integrada localmente. É um force push mais seguro, que garante que você realmente integrou os commits remotos novos antes de sobrescrevê-los. Só tem efeito junto com --force-with-lease (sem valor esperado explícito).

RecomendadoAdicione ao --force-with-lease para que um fetch em segundo plano não burle a garantia

Exemplo

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

Gerar saída legível por máquina. A linha de status de cada ref sai separada por tabulações e vai para o stdout em vez do stderr. Útil para scripts que interpretam os resultados do push.

Quando necessárioResultados legíveis por máquina para scripts

Exemplo

git push --porcelain origin main

Controlar como os submódulos são tratados no push. Valores: 'check' (falha se os commits dos submódulos não foram enviados), 'on-demand' (envia os commits dos submódulos se precisar), 'only' (só envia os submódulos), 'no' (sem recursão).

Quando necessárioGarante que os commits dos submódulos sejam enviados primeiro

Exemplo

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

Escolhendo a opção certa

A escada de segurança do force push

Quando precisar sobrescrever o histórico remoto, escolha a opção mais segura que sirva para a sua situação

ComandoNível de riscoConfere o remotoQuando falhaCaso de uso
git pushSeguro✓ Só fast-forwardSe o remoto tiver commits novosFluxo diário normal
git push --force-with-lease --force-if-includesO force mais seguro✓ Ponta remota no histórico localSe você não integrou as mudanças remotasDepois de rebase quando outros podem ter enviado
git push --force-with-leaseForce mais seguro✓ Remoto sem mudanças desde o fetchSe o remoto mudou desde o último fetchDepois de rebase em branch pessoal
git push --forcePerigoso✗ Sobrescreve às cegasNunca (a não ser que o servidor recuse)Só quando tiver certeza, ou em branch só sua

O que é enviado

Controlar o alcance do que você envia para o remoto

ComandoEnviaInclui tagsUso típico
git push origin mainUma branch✗Enviar uma branch específica
git push -u origin branchUma branch + configura rastreamento✗Primeiro push de uma branch nova
git push --allTodas as branches✗Sincronizar todas as branches locais
git push --tagsSó tags (sem branches)✓ Todas as tagsEnviar tags de versão
git push --follow-tagsBranch atual✓ Só as anotadas alcançáveisEnviar com as tags de release relevantes
git push --mirrorTudo✓ TudoClone exato no remoto (exclui refs que só existem no remoto)

Saída e retorno

Ajustar o nível de detalhe e o formato da saída à sua necessidade

ComandoNível de saídaMostra progressoLegível por máquinaIdeal para
git pushPadrãoSó no terminal✗Uso interativo normal
git push --verboseDetalhado✓✗Depurar problemas de push
git push --quietSó erros✗✗Scripts, pipelines de CI
git push --progressPadrão + progresso forçado✓ Sempre✗Scripts que precisam do progresso nos logs
git push --porcelainEstruturado✗✓ Separado por tabulaçõesInterpretar resultados do push em scripts

Segurança e verificação

Verificações antes do push e opções de conferência

ComandoRoda hooksVerificaCria commitQuando usar
git push✓ pre-pushO remoto aceitaN/AFluxo normal
git push --dry-run✓ pre-pushO que aconteceria✗ Só pré-visualizaçãoAntes de pushes importantes
git push --atomic✓Todas as refs ou nenhumaTudo ou nadaEnviar várias branches juntas
git push --no-verify✗ Pula o pre-push local (hooks do servidor ainda rodam)O remoto aceitaN/AEmergência quando os hooks bloqueiam você
git push --signed✓Assinatura GPGAssinado criptograficamenteRepositórios de alta segurança, provar identidade

Gerenciamento de remotos e branches

Opções para gerenciar refs remotas e relações entre branches

ComandoAçãoAfeta o remotoCaso de uso
git push -u origin branchPush + definir upstreamAdiciona branchPrimeiro push, configura rastreamento
git push origin --delete branchExcluir branch remotaRemove branchLimpar branches mescladas
git push --pruneExcluir branches remotas que você excluiu localmente (precisa de --all ou de um refspec curinga)Remove branchesLevar as exclusões ao remoto
git push --repo=<url>Enviar para um remoto específicoRemoto de destinoEnviar para outra URL remota

Exemplos de fluxos de trabalho

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

Adicionar a URL do repositório remoto

2
git push -u origin main

Enviar a branch main e fazer ela rastrear origin/main

1
git status

Conferir se está na branch certa e se há commits para enviar

2
git push

Enviar para a branch upstream rastreada

1
git checkout feature

Trocar para a sua branch de funcionalidade

2
git rebase main

Rebase sobre a main (reescreve o histórico de commits)

3
git push --force-with-lease

Forçar o push com segurança - falha se outra pessoa enviou algo

1
git checkout -b feature/new-login

Criar a branch nova e trocar para ela

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

Fazer as mudanças e o commit

3
git push -u origin feature/new-login

Enviar e configurar o rastreamento do upstream

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

Excluir a branch remota

2
git branch -d feature/old-branch

Excluir também a branch local

1
git push --all origin

Enviar todas as branches de refs/heads/

2
git push --tags origin

Opcionalmente, enviar também todas as tags

Solução de problemas

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

Causa: A branch remota tem commits que a sua branch local não tem. Outra pessoa enviou mudanças, ou você fez rebase/amend de commits que já tinham sido enviados.

Puxe antes as mudanças remotas com 'git pull --rebase' ou 'git pull --no-rebase', resolva eventuais conflitos e envie de novo. Só force (de preferência com '--force-with-lease') se tiver certeza de que ninguém mais usa a branch.

git pull --rebase && git push

git@github.com: Permission denied (publickey)

Causa: A autenticação SSH falhou: nenhuma chave está carregada, ou a sua chave pública não foi adicionada à sua conta. (Falta de permissão de escrita mostra outro erro, “Permission to ... denied”.)

Confira se a sua chave SSH foi adicionada à conta do GitHub/GitLab. Teste com 'ssh -T git@github.com'. Com HTTPS, garanta que está usando as credenciais certas.

ssh -T git@github.com

fatal: No configured push destination

Causa: O repositório não tem nenhum remoto configurado. (Se existe um remoto, mas a branch não tem upstream, aparece “The current branch ... has no upstream branch”.)

Adicione um remoto com 'git remote add origin <url>' e depois envie definindo o upstream com 'git push -u origin <branch>'.

git push -u origin main

Your branch is behind 'origin/main'

Causa: A branch remota tem commits mais novos do que a sua branch local. Você precisa integrar essas mudanças antes de enviar.

Busque as mudanças remotas e faça merge ou rebase delas na sua branch local antes de enviar.

git pull origin main && git push

refusing to update checked out branch

Causa: Você está tentando enviar para um repositório não bare em que essa branch está em checkout. Isso poderia deixar o diretório de trabalho dele inconsistente.

Envie para um repositório bare, ou peça que o receptor faça checkout de outra branch antes. Isso costuma acontecer em servidores próprios, não no GitHub/GitLab.

git config receive.denyCurrentBranch updateInstead

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

Causa: Erro genérico com várias causas possíveis: atualizações non-fast-forward, falhas de hooks ou problemas de permissão. Confira a mensagem de erro detalhada acima desta linha.

Leia a saída de erro inteira. Normalmente é um problema de non-fast-forward (faça pull antes) ou uma falha do hook pre-push (corrija o que o hook aponta).

git pull --rebase && git push

O hook pre-push falhou

Causa: Um hook pre-push (testes, lint etc.) encontrou problemas e bloqueou o push.

Corrija os problemas apontados pelo hook. Só pule com '--no-verify' se for absolutamente necessário e você entender as consequências.

git push --no-verify

remote: Repository not found

Causa: A URL do repositório está errada, o repositório foi excluído ou renomeado, ou você não tem acesso a ele.

Confira a URL do repositório com 'git remote -v'. Verifique se o repositório existe e se você tem acesso. Atualize a URL se precisar.

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

Dicas e armadilhas

Boas práticas

  • ✓Sempre faça pull antes do push: rode 'git pull' (ou 'git fetch' seguido de merge ou rebase) antes de enviar, para ter as mudanças remotas mais recentes e evitar pushes rejeitados.
  • ✓Use --force-with-lease em vez de --force: se precisar forçar, o --force-with-lease é mais seguro porque falha se outra pessoa enviou para o remoto desde o seu último fetch (adicione --force-if-includes para mais segurança).
  • ✓Defina o upstream no primeiro push: use 'git push -u origin branch-name' ao enviar uma branch nova para configurar o rastreamento. Depois basta 'git push'.
  • ✓Nunca force push em branches compartilhadas: forçar na main, master ou develop pode destruir o trabalho dos outros. Use commits de revert em vez de reescrever o histórico.
  • ✓Use regras de proteção de branch: configure o repositório para impedir force push em branches importantes e exigir revisão de pull requests.
  • ✓Envie com frequência para ter backup do trabalho: pushes regulares das branches de funcionalidade servem de backup e mostram o seu progresso.
  • ✓Confira antes de enviar: use 'git push --dry-run' para ver o que seria enviado sem enviar nada. Ótimo para conferir duas vezes.
  • ✓Limpe as branches remotas: exclua as branches de funcionalidade mescladas com 'git push origin --delete branch-name' para manter o remoto arrumado.
  • ✓Use pushes atômicos para mudanças relacionadas: ao enviar várias branches que dependem umas das outras, use '--atomic' para garantir que todas passem ou nenhuma.
  • ✓Assine pushes importantes: em repositórios críticos, use '--signed' para assinar os pushes com GPG e permitir a verificação (o servidor precisa aceitar pushes assinados, senão o push falha).

Erros comuns

  • ✗Fazer push sem pull antes: se o remoto tiver commits novos, o seu push será rejeitado. Sempre rode 'git pull' (ou fetch, depois merge/rebase) primeiro para incorporar as mudanças remotas.
  • ✗Usar --force em branches compartilhadas: forçar reescreve o histórico e pode destruir o trabalho dos outros. Use --force-with-lease ou, melhor ainda, evite totalmente force push em branches compartilhadas.
  • ✗Esquecer de definir o upstream com -u: no primeiro push de uma branch nova, use 'git push -u origin branch-name' para configurar o rastreamento. Senão, você vai precisar indicar remoto e branch toda vez.
  • ✗Enviar para a branch errada: confira a branch atual com 'git branch' antes do push. Use uma sintaxe explícita como 'git push origin feature:feature' para garantir.
  • ✗Não entender pushes rejeitados: erros de 'non-fast-forward' significam que o remoto tem commits que você não tem localmente. Faça pull e merge/rebase antes de enviar - não simplesmente force.

Perguntas frequentes

A:

'git push' envia os seus commits locais para um repositório remoto, deixando as suas mudanças disponíveis para os outros. 'git pull' baixa commits de um remoto e os mescla na sua branch local. O push manda dados para fora; o pull traz dados para dentro.

A:

Não dá para realmente “desfazer” um push, porque ele já é histórico compartilhado. Para reverter com segurança, use 'git revert HEAD' para criar um commit novo que desfaz as mudanças e envie de novo. Evite 'git reset' + force push em branches compartilhadas, pois isso reescreve um histórico que outros talvez já tenham puxado.

A:

A opção -u cria uma relação de rastreamento entre a sua branch local e a branch remota. Depois de 'git push -u origin feature', você pode usar só 'git push' e 'git pull', sem indicar o remoto e a branch toda vez.

A:

O force push (--force) só deve ser usado em branches em que só você contribui, como branches de funcionalidade pessoais depois de um rebase. Nunca force em branches compartilhadas como main ou develop. Se for mesmo preciso, use --force-with-lease por segurança.

A:

Use a sintaxe de refspec: 'git push origin local-branch:remote-branch'. Por exemplo, 'git push origin feature:experiment' envia a sua branch local 'feature' para uma branch remota chamada 'experiment'.

A:

Normalmente porque o remoto tem commits que você não tem localmente (non-fast-forward). Rode 'git pull' para buscar e mesclar essas mudanças, resolva eventuais conflitos e envie de novo. Não force, a menos que tenha certeza de que é seguro.

A:

Use 'git push --all origin' para enviar todas as branches locais para o remoto. As tags precisam de outro comando, porque '--all' e '--tags' não podem ser combinados: 'git push --tags origin'.

A:

'--force' sobrescreve a branch remota às cegas, seja qual for o estado dela. '--force-with-lease' só sobrescreve se o remoto não mudou desde o seu último fetch - falha se outra pessoa enviou algo, protegendo o trabalho dela. Atenção: um fetch (até o fetch em segundo plano de uma IDE) atualiza essa verificação, então adicione --force-if-includes para exigir também que você tenha integrado o que buscou.

A:

Use 'git push origin --delete branch-name' ou a forma curta 'git push origin :branch-name'. As duas removem a branch do repositório remoto.

A:

O 'git push' simples só funciona se a branch atual tiver uma branch upstream configurada. Para branches novas, você precisa antes de 'git push -u origin branch-name'. Confira as relações de rastreamento com 'git branch -vv'.