git remote

O que o git remote faz

Um remote é uma referência nomeada para outra cópia do seu repositório — geralmente uma hospedada em um servidor como GitHub, GitLab ou Bitbucket. O comando git remote cria, lista, renomeia e remove essas conexões. Ele não transfere commits por conta própria; em vez disso, armazena nomes curtos e fáceis de lembrar que apontam para URLs de repositórios, para que os comandos que realmente movem dados — git fetch, git pull e git push — possam referenciá-los.

Pense em um remote como um marcador. Em vez de digitar git push https://github.com/acme/app.git main toda vez, você salva a URL uma vez com o nome origin e executa git push origin main. O mapeamento de nomes para URLs fica no arquivo .git/config do seu repositório, portanto cada clone mantém sua própria lista de remotes.

O diagrama abaixo mostra duas conexões remotas de um repositório local: uma para um repositório central e outra para o repositório de outro desenvolvedor. Como os nomes são compartilhados por convenção, você pode dizer a um colega para "fazer pull do upstream" e ele saberá exatamente qual comando executar.

O remote origin

Executar git clone cria automaticamente um remote chamado origin que aponta de volta para o repositório que você clonou. Por convenção, origin é a cópia canônica "sua" no servidor — aquela para a qual você faz push e pull no dia a dia. Não há nada de especial no nome; é apenas o padrão que o Git escolhe, e você pode renomeá-lo ou removê-lo como qualquer outro remote.

Um segundo remote comum é o upstream. Quando você faz um fork de um projeto, origin aponta para o seu fork e upstream aponta para o repositório original, permitindo que você obtenha novas alterações do projeto enquanto envia seu próprio trabalho para o seu fork.

URLs de repositório

Uma URL de remote informa ao Git onde o repositório está localizado e qual protocolo de transporte usar. Os dois que você verá com mais frequência são HTTPS e SSH.

HTTPS é o mais simples de configurar e funciona através de firewalls e proxies. Repositórios públicos podem ser clonados via HTTPS sem credenciais; para repositórios privados ou para fazer push, o Git solicita um nome de usuário e um token de acesso pessoal, normalmente armazenado em cache por um auxiliar de credenciais.

https://host/path/to/repo.git

SSH autentica com um par de chaves em vez de uma senha, o que o torna conveniente para pushes repetidos após o registro da sua chave no servidor. Ele vem em duas formas equivalentes — a URL completa ssh:// e a sintaxe mais curta similar ao SCP:

ssh://user@host/path/to/repo.git

user@host:path/to/repo.git

Você não precisa memorizar o formato de uma URL; basta copiá-la do botão "Clone" do provedor de hospedagem. O comando git remote armazena o formato que você utilizou.

Subcomandos do git remote

O git remote expõe vários subcomandos. Cada um edita a seção de remote do .git/config; você poderia fazer as mesmas alterações manualmente em um editor de texto, mas os subcomandos são mais seguros e atualizam as configurações relacionadas para você.

git remote add

Registra um novo remote chamado <name> que aponta para <url>.

git remote add <name> <url>

Duas opções úteis:

• -f executa git fetch <name> imediatamente após criar o remote, fazendo o download dos seus branches de imediato.
• --tags busca o remote e também importa todas as suas tags.

git remote rename

Renomeia um remote de <old> para <new>, atualizando os branches de rastreamento remoto e qualquer configuração relacionada.

git remote rename <old> <new>

git remote remove

Exclui a conexão chamada <name> junto com seus branches de rastreamento remoto e configuração. git remote rm é um alias mais antigo para o mesmo comando.

git remote remove <name>

git remote set-url

Altera a URL para a qual um remote existente aponta — por exemplo, quando você muda um repositório de HTTPS para SSH.

git remote set-url <name> <new-url>

git remote get-url

Exibe a(s) URL(s) de um remote. Adicione --push para ver especificamente a URL de push, ou --all para listar todas as URLs configuradas.

git remote get-url <name>

git remote show

Exibe informações detalhadas sobre um remote: suas URLs de fetch e push, seus branches e como seus branches locais o rastreiam.

git remote show <name>

git remote prune

Remove branches de rastreamento remoto locais para <name> cujos equivalentes foram excluídos no servidor. Use --dry-run para listar o que seria removido sem realmente excluir nada.

git remote prune <name>

Listando seus remotes

Executar git remote sem argumentos exibe o nome de cada remote configurado, um por linha:

git remote
origin
upstream
other_repo

Adicione a flag -v (verbose) para ver também as URLs de fetch e push de cada remote:

git remote -v
origin      [email protected]:origin_user/reponame.git (fetch)
origin      [email protected]:origin_user/reponame.git (push)
upstream    https://example.com/upstream_user/reponame.git (fetch)
upstream    https://example.com/upstream_user/reponame.git (push)
other_repo  https://example.com/other_repo/reponame.git (fetch)
other_repo  https://example.com/other_repo/reponame.git (push)

Um remote pode ter uma URL de fetch diferente da URL de push — útil, por exemplo, quando você faz pull de um mirror rápido mas faz push para o servidor canônico.

Adicionando um remote

Para começar a colaborar com outro repositório, registre-o com git remote add. O nome que você escolher se torna um atalho que pode ser usado em fetch, pull e push:

git remote add upstream https://example.com/upstream_user/reponame.git

Conectar-se a repositórios de outros desenvolvedores permite a colaboração fora do repositório central. Por exemplo, se um colega mantém um repositório acessível publicamente em dev.example.com/tom.git, adicione-o assim e então busque o trabalho dele:

git remote add tom https://dev.example.com/tom.git
git fetch tom

Inspecionando um remote

O subcomando show entra em contato com o remote e exibe seus branches e configuração de rastreamento — útil quando você deseja confirmar qual branch será atualizado por um push ou pull:

git remote show upstream
* remote upstream
  Fetch URL: https://example.com/upstream_user/reponame.git
  Push  URL: https://example.com/upstream_user/reponame.git
  HEAD branch: main
  Remote branches:
    main      tracked
    docs      tracked
    new-input tracked
  Local ref configured for 'git push':
    main pushes to main (fast-forwardable)

Fetch, pull e push

Configurar um remote é apenas a etapa de configuração. Uma vez que ele existe, você passa seu nome para os comandos que realmente movem commits:

• git fetch <remote> baixa novos commits do remote para seus branches de rastreamento remoto sem alterar seus arquivos de trabalho.
• git pull <remote> <branch> busca e depois mescla (ou faz rebase) as alterações no seu branch atual.
• git push <remote> <branch> envia seus commits locais para o remote.

git push <remote-name> <branch-name>

Por exemplo, para publicar o branch main no origin:

git push origin main

Se você quiser se aprofundar em onde esses nomes e URLs são armazenados, consulte o capítulo git config, que documenta o arquivo .git/config que o git remote edita.

Prática