git mv

O comando git mv move ou renomeia um arquivo ou diretório que o Git já rastreia e prepara a alteração em uma única etapa. Este capítulo aborda como renomear um arquivo, mover um arquivo para um diretório, as opções que você realmente usará (-f, -n, -k) e os cuidados necessários — principalmente que git mv só funciona com arquivos que o Git já conhece e que o Git não armazena renomeações como registros.

Definição

git mv é um atalho conveniente. Executá-lo equivale a mover o arquivo manualmente, informar ao Git que o caminho antigo não existe mais com git rm e adicionar o novo caminho com git add — tudo de uma vez. A vantagem é que a árvore de trabalho e a área de preparação nunca ficam dessincronizadas, nem por um instante.

Renomeando um arquivo

Para renomear um arquivo rastreado, forneça o nome antigo e o nome novo:

git mv old-name.txt new-name.txt

O arquivo é renomeado no disco e a alteração já está preparada, pronta para o commit. Um git status subsequente exibe uma entrada de renomeação limpa. A forma abreviada torna isso evidente — o indicador R marca uma renomeação preparada:

git status --short

R  old-name.txt -> new-name.txt

Tudo o que resta é confirmar a alteração com git commit.

Movendo um arquivo para um diretório

Forneça um diretório como destino para mover um arquivo sem renomeá-lo:

git mv styles.css assets/

Você pode mover vários arquivos para um diretório em um único comando, desde que o destino seja uma pasta existente:

git mv main.css reset.css print.css assets/

Quando o último argumento é um diretório existente, todos os caminhos anteriores são movidos para ele. Se o diretório ainda não existir, o Git trata o último argumento como um novo nome de arquivo — portanto, crie a pasta primeiro (com mkdir) quando quiser mover arquivos para ela.

Renomeando um diretório

Passe um diretório rastreado como origem para movê-lo ou renomeá-lo junto com todo o seu conteúdo:

git mv src/ lib/

O Git prepara uma renomeação para cada arquivo rastreado dentro do diretório, então um único git mv pode gerar muitas entradas renamed: no git status.

O que o git mv economiza

Sem git mv, a mesma renomeação exige três etapas manuais:

mv old-name.txt new-name.txt
git rm old-name.txt
git add new-name.txt

git mv reduz tudo isso a um único comando e garante que a área de preparação permaneça consistente. Observe que o Git não armazena renomeações — ele as detecta comparando o conteúdo dos arquivos quando você executa git log ou git diff. O git mv simplesmente mantém a alteração na árvore de trabalho organizada e pré-preparada.

git mv só funciona em arquivos rastreados

git mv opera em arquivos que o Git já rastreia. Apontá-lo para um arquivo não rastreado resulta em erro:

git mv note.txt moved.txt

fatal: not under version control, source=note.txt, destination=moved.txt

Para um arquivo que o Git nunca viu, basta renomeá-lo com o mv comum do shell e depois preparar o novo nome com git add. Use git mv assim que o arquivo estiver confirmado.

Opções comuns

Quando o destino já existe

Por padrão, o Git se recusa a sobrescrever um arquivo existente. Se você pretende substituí-lo, adicione o sinalizador de força:

git mv -f draft.md final.md

Use isso com cuidado, pois descarta o conteúdo que estava no destino.

Visualizando com uma simulação

Antes de uma movimentação grande, use -n (ou --dry-run) para ver exatamente o que o Git faria — nada é renomeado e nada é preparado:

git mv -n old-name.txt new-name.txt

Checking rename of 'old-name.txt' to 'new-name.txt'
Renaming old-name.txt to new-name.txt

Combine com -v (verbose) para imprimir cada renomeação conforme ela acontece durante uma movimentação real.

Comandos relacionados

• git rm — remove arquivos rastreados; git mv executa um rm do caminho antigo internamente.
• git add — prepara alterações; git mv executa o add equivalente do novo caminho para você.
• git status — confirma a renomeação preparada antes de fazer o commit.
• git commit — registra a movimentação no histórico.
• git log — visualiza renomeações com git log --follow <file> para manter o histórico de um arquivo entre movimentações.

Prática