git clone

O que faz o git clone

O comando git clone copia um repositório existente para um novo diretório na sua máquina. Em uma única etapa ele:

• Cria o diretório de destino e inicializa um novo repositório local dentro dele (você não precisa executar git init antes).
• Baixa o histórico completo do projeto — cada commit, branch e tag.
• Adiciona o repositório de origem como um remoto chamado origin.
• Cria um branch de rastreamento remoto para cada branch no remoto e faz o checkout do branch padrão (geralmente main ou master) no seu diretório de trabalho.

É assim que quase todos os desenvolvedores obtêm uma cópia de trabalho de um projeto compartilhado, então git clone geralmente é o primeiro comando Git que você executa em um novo projeto.

Uso básico

A forma geral do comando recebe uma URL de repositório e, opcionalmente, um nome de diretório:

git clone <repo> [<directory>]

Por exemplo, clonar um projeto via SSH de um servidor acessível em example.com usando o nome de usuário x_person:

git clone ssh://[email protected]/path/to/team-project.git
cd team-project
# Start editing files, committing snapshots, and pushing to the remote

Isso inicializa um novo repositório na pasta team-project e o preenche com o conteúdo do repositório central. Após a clonagem, você pode usar cd para entrar no projeto e começar a modificar arquivos, fazer commits de snapshots e interagir com o remoto.

Clonando em uma pasta específica

Por padrão, o Git nomeia o novo diretório com o nome do repositório. Para clonar em uma pasta de sua escolha, adicione um argumento <directory>:

git clone https://example.com/team-project.git my-project
cd my-project

Isso clona o repositório em my-project em vez de team-project.

Clonando um único branch ou tag

Passe --branch (abreviação: -b) com um nome de branch ou tag para fazer o checkout de algo diferente do branch padrão do remoto:

# Check out the develop branch instead of the default
git clone --branch develop https://example.com/team-project.git

# Check out the state at tag v1.0 (results in a detached HEAD)
git clone --branch v1.0 https://example.com/team-project.git

Quando você passa uma tag, a árvore de trabalho é verificada nessa tag em um estado detached HEAD, pois uma tag não é um branch para o qual você pode fazer commit.

Opções úteis do clone

Essas opções permitem personalizar o que git clone baixa e como o novo repositório se comporta.

--depth (clone superficial)

--depth <n> cria um clone superficial que mantém apenas os últimos <n> commits em vez do histórico completo. Isso é muito mais rápido para repositórios grandes e é comum em pipelines de CI onde o histórico completo não é necessário.

git clone --depth 1 https://example.com/team-project.git

--single-branch

--single-branch baixa o histórico de apenas um branch (o branch padrão ou o indicado por --branch) em vez de todos os branches. É implicitado por --depth.

git clone --single-branch --branch main https://example.com/team-project.git

--recurse-submodules

Se o projeto usa submódulos, --recurse-submodules clona e faz o checkout deles na mesma etapa, para que você não precise executar git submodule update --init depois.

git clone --recurse-submodules https://example.com/team-project.git

-o (renomear o remoto)

Por padrão, a origem é adicionada como remoto origin. Use -o <name> para escolher um nome diferente. Consulte git remote para gerenciar remotos posteriormente.

git clone -o upstream https://example.com/team-project.git

--bare e --mirror

• --bare cria uma cópia do repositório sem um diretório de trabalho. O repositório resultante contém o histórico do projeto e pode receber push ou pull, mas não possui arquivos verificados para edição. Esse é o formato usado para repositórios que residem em um servidor.
• --mirror implica --bare, mas vai além: copia todas as refs (branches, tags, notas, refs de rastreamento remoto) e configura o remoto para que o espelho permaneça um reflexo exato da origem. É usado principalmente para mover ou fazer backup de um repositório.

git clone --bare https://example.com/team-project.git
git clone --mirror https://example.com/team-project.git

Diferença entre git init e git clone

git init e git clone são frequentemente confundidos. A distinção principal:

• git init cria um repositório local vazio e totalmente novo — não há remoto nem histórico ainda.
• git clone copia um repositório remoto existente para sua máquina, trazendo seu histórico completo e configurando o origin automaticamente.

git clone não exige que você execute git init antes; ele inicializa o repositório local e configura os branches de rastreamento remoto para você.

URLs do Git

O Git tem sua própria sintaxe de URL para informar aos comandos onde um repositório remoto está localizado. Como git clone quase sempre tem como alvo um remoto, entender essas URLs é importante. O Git suporta quatro famílias de protocolos: Git, SSH, HTTPS e Local. Todos eles, exceto HTTPS, exigem que o Git esteja instalado e em execução no servidor.

Protocolo Git

O protocolo Git é exclusivo do Git. Ele é servido por um daemon que escuta na porta 9418 e oferece acesso anônimo de leitura principalmente, semelhante ao SSH, mas sem nenhuma autenticação.

git clone git://host.xz/path/to/repo.git

Sua vantagem é a transferência rápida. Suas desvantagens são a falta de autenticação (por isso raramente é usado para gravações) e uma configuração de servidor mais complexa.

Protocolo SSH

Secure Shell (SSH) é um protocolo de rede para fazer login de um computador para outro com segurança. É o protocolo mais comum para acesso autenticado de leitura/gravação, e o acesso SSH é configurado por padrão na maioria das plataformas de hospedagem. Você deve estabelecer credenciais (uma chave SSH) com o servidor antes de se conectar.

git clone ssh://user@server/project.git

# Many hosts also accept the shorter "scp-like" form:
git clone user@server:project.git

O SSH criptografa e autentica todo o tráfego, comprime os dados antes da transferência e é fácil de configurar. Sua principal limitação é que não suporta acesso anônimo. Consulte nossa seção de chave SSH para configurar chaves.

Protocolo HTTPS

HTTPS (HyperText Transfer Protocol Secure) é o protocolo usado para transmitir dados com segurança pela web, e o Git pode compartilhar repositórios por meio dele.

git clone https://example.com/gitproject.git

HTTPS é simples de configurar, criptografa a transferência e passa facilmente pelos firewalls corporativos (a porta 443 está quase sempre aberta), o que o torna um dos protocolos mais amplamente usados. Sua principal desvantagem é uma sobrecarga ligeiramente maior da criptografia, o que pode tornar a clonagem marginalmente mais lenta do que o protocolo Git puro.

Protocolo Local

Com o protocolo Local, o repositório "remoto" é simplesmente outro diretório no mesmo disco ou em um sistema de arquivos compartilhado. Quando os membros da equipe compartilham um sistema de arquivos, eles podem clonar, fazer push e pull por meio de caminhos simples.

git clone /opt/git/project.git

# Or with an explicit file:// URL:
git clone file:///opt/git/project.git

Comandos relacionados

Após a clonagem, estes capítulos cobrem o fluxo de trabalho diário:

• git fetch e git pull — baixar e integrar atualizações do remoto.
• git branch e git checkout — criar e alternar entre branches.
• git remote — visualizar e gerenciar o remoto origin que o git clone configurou.

Prática