git clone: como clonar um repositório do GitHub e de outros servidores

O comando git clone cria uma cópia local completa de um repositório remoto: arquivos, todo o histórico de commits, branches e tags. É a forma padrão de começar a trabalhar em um projeto que já está no GitHub, no GitLab ou em um servidor corporativo. Diferente de baixar um ZIP, o clone é um repositório de verdade, no qual você pode fazer commits e enviar as alterações de volta.

Uso básico do git clone

Copie o endereço do repositório (no GitHub, o botão verde "Code") e execute:

git clone https://github.com/username/project.git

Cloning into 'project'...
remote: Enumerating objects: 1532, done.
remote: Counting objects: 100% (1532/1532), done.
remote: Compressing objects: 100% (812/812), done.
Receiving objects: 100% (1532/1532), 2.41 MiB | 6.10 MiB/s, done.
Resolving deltas: 100% (701/701), done.

O Git cria a pasta project no diretório atual (o nome vem do endereço, sem o .git). Depois, entre nela:

cd project
git status

O que o git clone faz por baixo dos panos

Clonar não é só baixar arquivos. Entender essas etapas explica por que, depois do clone, tudo "simplesmente funciona" e de onde vêm as branches com o prefixo origin/. Passo a passo, o comando:

1. cria a pasta e executa nela o equivalente a git init;
2. adiciona um remote chamado origin, apontando para o endereço de origem;
3. baixa todos os objetos e referências — o equivalente a git fetch;
4. cria as branches remotas origin/main, origin/develop e assim por diante;
5. cria a branch local padrão (normalmente main), vincula-a a origin/main e extrai os arquivos.

Por isso, depois do clone não é preciso configurar o git remote à mão — git push e git pull funcionam de imediato.

git remote -v
origin  https://github.com/username/project.git (fetch)
origin  https://github.com/username/project.git (push)

Clonar via HTTPS e via SSH

Para ler projetos abertos de outras pessoas, HTTPS basta. Para os seus repositórios, nos quais você faz push com frequência, SSH é mais prático:

git clone git@github.com:username/project.git

Se você já clonou via HTTPS e quer passar para SSH, não precisa baixar tudo de novo:

git remote set-url origin git@github.com:username/project.git

Como clonar em uma pasta específica

O segundo argumento é o nome ou o caminho do diretório de destino:

# Em uma pasta com outro nome
git clone https://github.com/username/project.git my-copy

# Na pasta atual (ela precisa estar vazia)
git clone https://github.com/username/project.git .

Se a pasta de destino existe e não está vazia, o Git recusa: fatal: destination path 'project' already exists and is not an empty directory.

Como clonar uma branch específica

Por padrão, depois do clone você fica na branch padrão do repositório remoto. Para cair direto em outra, use -b (--branch):

git clone -b develop https://github.com/username/project.git

Atenção: assim todas as branches são baixadas, você só fica posicionado na develop. Se precisa de apenas uma branch, sem as outras, adicione --single-branch:

git clone -b develop --single-branch https://github.com/username/project.git

A flag -b também aceita o nome de uma tag — nesse caso você recebe o estado do projeto no momento do release (em modo detached HEAD):

git clone -b v2.1.0 --depth 1 https://github.com/username/project.git

Onde estão as outras branches depois do clone

Iniciantes se surpreendem: git branch mostra só a main. As outras branches foram baixadas como remotas, e dá para vê-las assim:

git branch -a

* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/develop
  remotes/origin/feature/login

Para começar a trabalhar em uma delas, basta mudar para ela pelo nome curto — o Git cria sozinho uma branch local que rastreia a remota:

git switch develop

Clone raso: --depth para repositórios grandes

Em projetos antigos, o histórico pode pesar gigabytes. Se você só precisa do código atual — por exemplo, no CI ou apenas para compilar o projeto —, baixe só os últimos commits:

git clone --depth 1 https://github.com/username/big-project.git

A flag --depth implica --single-branch, então chegam apenas a branch padrão e um commit. Se mais tarde precisar do histórico completo, dá para baixá-lo:

git fetch --unshallow

Também é possível indicar outra profundidade, por exemplo --depth 50, ou limitar o histórico por data com --shallow-since=2025-01-01. Para desenvolvimento ativo, o clone raso é incômodo: git log, git blame e a busca no histórico ficam incompletos.

Clone parcial: --filter

Uma alternativa para monorepos enormes é baixar o histórico de commits, mas carregar o conteúdo dos arquivos sob demanda:

git clone --filter=blob:none https://github.com/username/monorepo.git

Assim você mantém o histórico completo para o log e para trocar de branch, mas economiza tráfego e espaço. Exige suporte do servidor; GitHub e GitLab oferecem.

Clone espelho e migração de repositório

O clone comum traz as branches como remotas e não copia as referências internas do servidor. Para migrar um projeto para outra hospedagem ou criar um backup idêntico, usa-se --mirror:

git clone --mirror https://github.com/username/project.git
cd project.git
git push --mirror git@gitlab.com:username/project.git

O espelho é um repositório bare, sem arquivos de trabalho, em que todas as branches e tags ficam como locais. O comando git push --mirror envia tudo para o novo servidor e o histórico é migrado sem perdas. Lembre-se de que issues, pull requests e configurações da hospedagem não são migrados assim — esses são dados do serviço, não do Git.

A flag parecida --bare também cria um repositório sem diretório de trabalho, mas copia só branches e tags. Ela serve para montar um repositório central no seu próprio servidor a partir de um projeto existente.

Clonar com submódulos

Se o projeto usa git submodules, por padrão as pastas deles ficarão vazias. Para baixar tudo de uma vez:

git clone --recurse-submodules https://github.com/username/project.git

Se você já clonou sem a flag, baixe os submódulos depois:

git submodule update --init --recursive

git clone, fork e download do ZIP

Fork e clone não competem: em open source, primeiro se faz o fork no site, depois se clona o seu fork e se adiciona o original como segundo remote:

git clone git@github.com:me/project.git
cd project
git remote add upstream https://github.com/author/project.git
git fetch upstream

Erros comuns do git clone

"Repository not found"

Erro de digitação no endereço ou o repositório é privado e você não tem acesso. Para repositórios privados, o GitHub responde de propósito "not found", e não "acesso negado". Confira o endereço e se você está autenticado na conta certa.

"Permission denied (publickey)"

Clone via SSH, mas a chave não está configurada. Teste com ssh -T git@github.com, adicione a chave pública nas configurações da conta ou clone temporariamente via HTTPS.

"Authentication failed" via HTTPS

Você digitou a senha da conta. Há muito tempo o GitHub exige um Personal Access Token no lugar da senha para operações Git via HTTPS. Se o Git guardou dados errados, apague-os no gerenciador de credenciais do sistema.

Queda no meio de um repositório grande

Erros como early EOF ou RPC failed costumam estar ligados a rede instável e ao tamanho. Ajuda um clone raso com --depth 1 seguido de git fetch --unshallow, ou clonar via SSH.

Problemas com quebras de linha no Windows

Depois do clone, todos os arquivos aparecem "modificados" — é assim que se manifesta a conversão CRLF/LF. Configure git config --global core.autocrlf true no Windows (ou input no Linux e no macOS) e, de preferência, defina regras no .gitattributes do projeto.

O que fazer logo depois de clonar

O clone está pronto, mas antes de mexer no código vale gastar alguns minutos com a preparação. Isso evita os problemas típicos logo no primeiro dia num projeto de outra pessoa.

1. Leia o README e o CONTRIBUTING. Normalmente eles explicam como instalar as dependências, rodar os testes e como o projeto costuma nomear as branches.
2. Confira a branch e o estado. git status e git log --oneline -5 mostram onde você está e quais foram as últimas alterações.
3. Crie a sua branch. Não trabalhe direto na main: git switch -c feature/my-task.
4. Confira o autor dos commits. Se o computador tem várias contas (pessoal e do trabalho), defina o e-mail só para este repositório, sem --global: git config user.email "you@company.com".
5. Instale as dependências. Pastas como node_modules ou venv não vão para o repositório, elas são criadas localmente: npm install, pip install -r requirements.txt e assim por diante.

Como manter o clone atualizado

O clone é feito uma única vez. Depois, os novos commits dos colegas são trazidos do mesmo origin:

# Ver o que chegou no servidor, sem alterar nada
git fetch
git log --oneline main..origin/main

# Integrar as alterações na branch atual
git pull

O hábito de fazer primeiro git fetch e olhar o que chegou poupa conflitos inesperados. Não é preciso clonar o projeto de novo "para atualizar" — assim você perde as branches locais e o trabalho não commitado.

Cola do git clone

Resumo

O git clone baixa o repositório inteiro e já configura a ligação com o servidor via origin, então depois dele você pode fazer commit, push e pull sem configuração extra. Para os seus projetos use SSH, para os grandes --depth ou --filter, para a branch desejada -b. O trabalho com repositórios remotos, push, pull e fetch é praticado no curso de Git.