-u | --set-upstream
Quando seu branch não está mapeado para um repositório remoto de upstream, você pode usar essa configuração para setar e empurrar ao mesmo tempo para empurrar e, caso dê sucesso o push, setar o upstream como sendo do remoto para o qual empurrou. Se você empurrar múltiplos branches, todos que tiveram sucesso vão ter o upstream tracking atualizado.
Eu particularmente só usava a versão longa, não conhecia a abreviação dela.
Referência: https://git-scm.com/docs/git-push#git-push--u
Exemplo de uso (empurrando o branch feature-upstream
para o remoto origin
):
git push origin -u feature-upstream
Caso o que você esteja trabalhando em um branch local não rastreado e tentar dar um git push
, o próprio git
sugerirá a você o comando que provavelmente você quer, que seria o git push -u
/git push --set-upstream
:
$ git push
fatal: The current branch feature-upstream has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin feature-upstream
Você também pode usar o git push -u
para empurrar branchs específicos de um remoto para outro. Por exemplo, tenho um servidor interno origin
, gostaria de enviar o branch master
dele para o servidor externo gitlab
.
Uma alternativa mais grossa seria fazer:
git checkout origin/master -b master
git push -u gitlab master
Isso altera minha cópia de trabalho. Mas também é possível subir diretamente o master
:
git push -u gitlab +origin/master:refs/heads/master
Assim eu consigo empurrar o branch de um remoto para outro sem precisar modificar minha cópia de trabalho.
Explicando:
+origin/master:refs/heads/master
nome de um <refspec>
; o sinal de +
é opcional, seu formato é +<src>:<dst>
origin/master
como <src>
indicativo de fonte do branch; pode ser um SHA1 também, ou qualquer coisa treeish
refs/heads/master
como <dst>
indicativo de destino; no caso de um branch, ele é uma cabeça de referência, daí refs/heads
; no caso, eu quis salvar o nome do branch como master
Os seguintes branchs eu subi no https://gitlab.com usando os seguintes comandos:
# eu estou com a cópia de trabalho no develop
git push -u gitlab develop
# sem mudar minha cópia de trabalho...
git push -u gitlab +origin/master:refs/heads/master

Também funcionou (quando já há o branch develop
no remoto gitlab
):
git push -u gitlab +origin/develop:develop
equivalente a:
git push -u gitlab +origin/develop:refs/heads/develop
mas eu preferi o +origin/develop:develop
porque é muito costumeiro, para mim, esquecer o plural de cabeças e digitar apenas +origin/develop:refs/head/develop
com cabeça no singular.
Vale a pena usar o com refs/heads
quando o branch não não existe no remoto em questão. Por exemplo:
$ git push -u gitlab +origin/feature-des-bounce:feature-des-bounce
error: unable to push to unqualified destination: feature-des-bounce
The destination refspec neither matches an existing ref on the remote nor
begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@gitlab.com:my-awesome-project.git'
$ git push -u gitlab +origin/feature-des-bounce:refs/heads/feature-des-bounce
Counting objects: 20, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (20/20), 1.72 KiB | 879.00 KiB/s, done.
Total 20 (delta 11), reused 16 (delta 7)
remote:
remote: To create a merge request for feature-des-bounce, visit:
remote: https://gitlab.com/my-awesome-project/merge_requests/new?merge_request%5Bsource_branch%5D=feature-des-bounce
remote:
To gitlab.com:my-awesome-project.git
* [new branch] origin/feature-des-bounce -> feature-des-bounce
O comentário que o Ricardo Moraleida deixou resume bem o uso:
Trocando em miúdos: é uma configuração de cada branch local para determinar qual branch remoto vai ser chamado se vc usar git pull ou git fetch sem argumentos. Sem essa configuração esses comandos retornam com erro a menos que se especifique o remote e branch de origem, como em git pull origin master.