git add

Snapshots básicos

Adicionar o conteúdo dos arquivos ao índice (área de preparação)

O comando 'git add' atualiza o índice com o conteúdo atual da árvore de trabalho, para preparar o conteúdo do próximo commit. O índice, também chamado de área de preparação, é o que você usa para preparar o conteúdo do próximo commit. Quando você roda 'git commit' sem outros argumentos, só as mudanças preparadas vão para o commit. Este comando pode ser rodado várias vezes antes de um commit para adicionar mudanças aos poucos.

Sinopse

git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] [--all | -A] [--update | -u] [--] [<pathspec>...]
[ ] opcional| ou<arg> valor a substituir... repetível--flag opção

Opções

Clique em uma opção para expandir

Iniciante (4)

Preparar tudo de uma vez - todos os arquivos novos, modificações e exclusões do projeto inteiro.

Quando necessárioPrepara tudo, exclusões incluídas — confira o git status antes para nada indesejado entrar

Exemplo

git add -A

Preparar só mudanças em arquivos que o Git já conhece. Arquivos novos não rastreados são ignorados.

Quando necessárioPrepara só mudanças de arquivos rastreados — útil quando os arquivos novos ainda não estão prontos

Exemplo

git add -u

Ver exatamente quais arquivos estão sendo preparados enquanto o comando roda. Mostra cada nome de arquivo quando ele é adicionado.

Quando necessárioLista cada arquivo enquanto é preparado; útil em adds grandes

Exemplo

git add -v .

Ver o que seria preparado sem preparar nada. Ótimo para conferir antes do commit.

RecomendadoPrévia inofensiva do que um add amplo prepararia

Exemplo

git add -n .

Intermediário (5)

Escolher de forma interativa quais partes de um arquivo preparar. Perfeito para dividir mudanças grandes em commits focados.

RecomendadoRevise e prepare exatamente os hunks que pertencem a este commit

Exemplo

git add -p

Abrir uma interface completa com menus para gerenciar a preparação. Permite preparar, tirar da preparação e revisar mudanças de forma interativa.

Quando necessárioPreparação por menu; o -p cobre a maioria das necessidades de forma mais direta

Exemplo

git add -i

Preparar um arquivo normalmente ignorado pelo .gitignore. Use quando precisar passar por cima das regras de exclusão.

Quando necessárioPrepara arquivos ignorados — confirme que o arquivo realmente pertence ao repositório

Exemplo

git add -f dist/bundle.js

Registrar que um arquivo será adicionado depois, sem preparar o conteúdo. Útil para mostrar arquivos novos no 'git diff'.

Quando necessárioTorna arquivos novos visíveis para git diff e add -p antes de prepará-los

Exemplo

git add -N newfile.js

Silenciar o aviso ao adicionar um repositório aninhado (uma pasta com o próprio .git) ao índice. Use quando você quer mesmo adicionar um repositório git aninhado.

Não recomendadoNormalmente você quer git submodule add em vez de um repositório aninhado puro

Exemplo

git add --no-warn-embedded-repo vendor/library

Avançado (6)

Abrir o diff no seu editor antes de preparar. Você escolhe à mão quais mudanças incluir.

Quando necessárioEditar o diff à mão antes de preparar; é fácil gerar um patch que não se aplica

Exemplo

git add -e app.js

Não adicionar arquivos, só atualizar as informações de stat() deles no índice. Precisa de um pathspec. Útil depois de mudanças só de horário.

Quando necessárioSó atualiza as informações dos arquivos no índice; o git status já faz isso

Exemplo

git add --refresh .

Continuar adicionando arquivos mesmo que alguns falhem por erros. O comando ainda termina com código diferente de zero.

Quando necessárioPula os arquivos que não podem ser adicionados; o comando ainda termina com código diferente de zero

Exemplo

git add --ignore-errors .

Verificar se arquivos seriam ignorados, mesmo que ainda não existam. Só funciona com --dry-run.

Quando necessárioSó com --dry-run: verifica as regras de exclusão mesmo para caminhos inexistentes

Exemplo

git add -n --ignore-missing *.tmp

Preparar arquivos novos e modificados, mas ignorar arquivos removidos da árvore de trabalho. Alias: --ignore-removal. Só tem efeito junto com um pathspec (por ex. git add --no-all .).

Não recomendadoComportamento antigo, anterior ao 2.0, que deixa exclusões sem preparar sem avisar

Exemplo

git add --no-all .

Gerar os trechos mostrados por -p/-i com <n> linhas de contexto em vez das 3 padrão (ou diff.context). Requer Git 2.51 ou mais recente — versões mais antigas o rejeitam com "unknown switch `U'".

Quando necessárioMais linhas de contexto nos hunks do add -p — exige Git 2.51 ou mais recente

Exemplo

git add -p -U5 app.js

Especialista (6)

Substituir o bit de execução dos arquivos adicionados. Use +x para tornar executável e -x para remover.

Quando necessárioLiga o bit de execução no índice — útil no Windows

Exemplo

git add --chmod=+x script.sh

Reaplicar o filtro 'clean' a todos os arquivos rastreados. Útil depois de mudar as configurações de final de linha.

Quando necessárioRode uma vez depois de mudar as regras de final de linha do .gitattributes

Exemplo

git add --renormalize .

Permitir atualizar entradas do índice fora do cone do sparse checkout. Só para sparse checkouts avançados.

Quando necessárioSó para repositórios com sparse checkout que editam caminhos fora do cone

Exemplo

git add --sparse path/outside/cone

Ler caminhos de arquivos de um arquivo em vez da linha de comando. Use '-' para ler do stdin.

Quando necessárioPara scripts com muitos caminhos; evita os limites de tamanho da linha de comando

Exemplo

git add --pathspec-from-file=files.txt

Em -p/-i, mostrar o contexto entre trechos até o número de linhas indicado, juntando em um só os trechos próximos (0 por padrão, ou diff.interHunkContext). Requer Git 2.51 ou mais recente.

Quando necessárioFunde hunks próximos no add -p — exige Git 2.51 ou mais recente

Exemplo

git add -p --inter-hunk-context=5

Usado com --pathspec-from-file. Os elementos do pathspec são separados pelo caractere NUL em vez de quebras de linha. Lida com nomes de arquivo com caracteres especiais.

Quando necessárioComplemento do --pathspec-from-file para nomes com quebras de linha ou caracteres estranhos

Exemplo

git add --pathspec-from-file=files.txt --pathspec-file-nul

Escolhendo a opção certa

Comandos de preparação

Quais arquivos são preparados por cada comando

ComandoArquivos novosArquivos modificadosArquivos excluídosAlcance
git add <file>✓✓✓Só o arquivo indicado
git add .✓✓✓Diretório atual e abaixo
git add -A✓✓✓Repositório inteiro
git add -u✗✓✓Só arquivos rastreados
git add --no-all✓✓✗Ignora exclusões

Opções interativas

Opções para controlar em detalhe o que é preparado

ComandoModoGranularidadeCaso de uso
git add -pPatchTrecho a trechoPreparar mudanças específicas de um arquivo
git add -eEditorLinha a linhaEditar o diff à mão antes de preparar
git add -iMenuArquivo a arquivoMenu de preparação interativo completo

Opções de pré-visualização e saída

Opções que mostram informações sem modificar a área de preparação

ComandoAçãoModifica o índicePropósito
git add -nDry-run✗Pré-visualizar o que seria preparado
git add -vDetalhado✓Mostrar os arquivos à medida que são preparados
git add --refreshAtualizar✗Atualizar só as informações de stat

Arquivos especiais

Opções para arquivos que precisam de tratamento especial

ComandoLida comComportamentoUso típico
git add -fArquivos ignoradosPassar por cima do .gitignoreAdicionar um arquivo normalmente ignorado
git add -NArquivos novosIntenção de adicionar (vazio)Rastrear um arquivo para o git diff sem prepará-lo
git add --chmod=+xExecutáveisDefinir o modo do arquivoTornar scripts executáveis
git add --sparseArquivos sparseFora do conePreparar arquivos fora do sparse checkout

Opções avançadas

Opções de nível avançado para cenários específicos

ComandoPropósitoQuando usar
git add --renormalizeReaplicar os filtros cleanDepois de mudar os finais de linha no .gitattributes
git add --pathspec-from-fileLer caminhos de um arquivoPreparar muitos arquivos a partir de uma lista
git add --ignore-errorsContinuar apesar de errosPrepare o que der e pule as falhas
git add --no-warn-embedded-repoSilenciar o aviso de submóduloAdicionar repositórios aninhados de propósito

Exemplos de fluxos de trabalho

1
git status

Revisar primeiro todas as mudanças

2
git add -A

Preparar todos os arquivos novos, modificados e excluídos

3
git commit -m "Your message"

Fazer commit de todas as mudanças preparadas

1
git add -p

Escolher de forma interativa só as mudanças da correção (aperte 'y' nos trechos da correção e 'n' nos da funcionalidade)

2
git commit -m "Fix login validation bug"

Fazer commit só da correção

3
git add -A

Agora preparar as mudanças restantes da funcionalidade

4
git commit -m "Add dark mode toggle"

Fazer commit da funcionalidade separadamente

1
git status

Ver o que está modificado e o que não é rastreado

2
git add -u

Preparar só as modificações de arquivos rastreados

3
git status

Conferir que os arquivos novos continuam não rastreados

4
git commit -m "Update existing files"

Fazer commit sem os arquivos novos

1
git add -n .

O dry-run mostra o que seria adicionado

2
git diff

Revisar em detalhe as mudanças reais

3
git add .

Se estiver tudo certo, preparar de verdade

1
git add dist/bundle.js

Isto falha - o arquivo é ignorado

2
git add -f dist/bundle.js

Forçar a adição passa por cima do .gitignore

3
git commit -m "Add build for deployment"

Fazer commit do arquivo normalmente ignorado

Teclas do modo interativo

Atalhos de teclado dos modos interativos do git add. Funcionam no modo patch (-p) e no modo interativo (-i).

Modo patch

-p
yPreparar este trecho
nNão preparar este trecho
qSair; não preparar este trecho nem os restantes
aPreparar este trecho e todos os seguintes do arquivo
dNão preparar este trecho nem os seguintes do arquivo
sDividir o trecho atual em trechos menores
eEditar o trecho atual à mão
?Mostrar a ajuda

Modo interativo

-i
1 / sStatus - mostrar o estado atual da preparação
2 / uUpdate - escolher os arquivos a preparar
3 / rRevert - tirar da preparação os arquivos escolhidos
4 / aAdd untracked - adicionar arquivos novos
5 / pPatch - entrar no modo patch para os arquivos escolhidos
6 / dDiff - mostrar o diff das mudanças preparadas
7 / qSair
8 / hAjuda

Solução de problemas

O arquivo não é adicionado (ignorado)

Causa: O arquivo corresponde a um padrão do .gitignore

Procure o padrão correspondente no .gitignore. Use -f para forçar a adição, se for intencional.

git add -f <file>

Erro “Permission denied”

Causa: O arquivo está bloqueado por outro processo ou você não tem permissão de leitura

Feche os aplicativos que usam o arquivo ou confira as permissões. Use --ignore-errors para continuar com os outros arquivos.

git add --ignore-errors .

Nada acontece ao rodar git add

Causa: Talvez os arquivos já estejam preparados, ou não há mudanças para adicionar

Rode git status para ver o estado atual. Arquivos já preparados não são adicionados de novo.

git status

Arquivos novos não aparecem no git diff

Causa: Arquivos não rastreados não aparecem no git diff por padrão

Use git add -N para marcar a intenção de adicionar; aí o git diff mostra o conteúdo.

git add -N <file> && git diff

Aviso sobre repositório git aninhado

Causa: Você está adicionando uma pasta que tem o próprio diretório .git (um repositório aninhado)

Remova a pasta .git aninhada, use submódulos do git ou silencie o aviso.

git add --no-warn-embedded-repo <folder>

Os finais de linha continuam aparecendo como mudanças

Causa: Finais de linha inconsistentes (CRLF ou LF) entre o seu sistema e o repositório

Configure o .gitattributes com 'text=auto' e renormalize todos os arquivos.

git add --renormalize .

Scripts (por ex. git diff-files) listam arquivos como modificados, mas o conteúdo não mudou

Causa: Os horários dos arquivos mudaram, então as informações de stat guardadas no índice estão desatualizadas

Atualize o índice para renovar as informações de stat sem preparar nada. (O git status atualiza automaticamente.)

git add --refresh .

Dicas e armadilhas

Boas práticas

  • ✓Revise as mudanças antes de prepará-las: use 'git diff' para ver o que você vai preparar, ou 'git add -p' para revisar de forma interativa.
  • ✓Prepare juntas as mudanças relacionadas: agrupe em um único commit as mudanças logicamente relacionadas. Não misture correções de bugs com funcionalidades novas.
  • ✓Use 'git add -p' para mudanças grandes: quando você fez várias mudanças sem relação em um arquivo, use o modo patch para prepará-las separadamente.
  • ✓Confira o git status com frequência: sempre rode 'git status' antes e depois de preparar para verificar o que vai para o commit.
  • ✓Cuidado com 'git add .': ele prepara tudo no diretório atual. Considere indicar arquivos específicos ou usar 'git add -p' para ter mais controle.
  • ✓Configure o .gitignore primeiro: antes do seu primeiro 'git add', garanta que o .gitignore exclua artefatos de build, dependências e arquivos sensíveis.
  • ✓Use o dry-run para conferir: na dúvida, use 'git add -n .' para ver o que seria preparado sem preparar nada.
  • ✓Prepare exclusões explicitamente: excluir um arquivo localmente não prepara a exclusão. Use 'git add -u' ou 'git add -A' para incluir as exclusões.

Erros comuns

  • ✗'git add .' ou 'git add -A': os dois preparam arquivos novos, modificados e excluídos, mas '.' só cobre o diretório atual para baixo, enquanto '-A' cobre a árvore de trabalho inteira.
  • ✗Esquecer que 'git add' não faz commit. Os arquivos só ficam preparados e precisam de 'git commit' para serem registrados.
  • ✗Adicionar arquivos que deveriam ser ignorados. Sempre confira o seu .gitignore antes de rodar 'git add -A' ou 'git add .'
  • ✗Não revisar as mudanças antes de prepará-las. Use 'git add -p' para revisar com mais cuidado o que você prepara.
  • ✗Confundir 'git add -u' com 'git add -A': '-u' só prepara modificações e exclusões de arquivos rastreados, não arquivos novos não rastreados.

Perguntas frequentes

A:

Desde o Git 2.0 os dois preparam arquivos novos, modificados e excluídos. A diferença é o alcance: 'git add .' só cobre o diretório atual e os subdiretórios, enquanto 'git add -A' cobre o repositório inteiro, seja qual for o seu diretório atual.

A:

Provavelmente o arquivo está listado no .gitignore. Confira com 'git check-ignore <file>'. Se precisar adicioná-lo mesmo assim, force com 'git add -f <file>'.

A:

Sim! Use 'git restore --staged <file>' (ou 'git reset HEAD <file>' em versões antigas do Git) para tirar um arquivo da preparação sem perder as suas mudanças.

A:

Use 'git add -p <file>' para entrar no modo patch interativo. O Git mostra cada mudança (hunk) e deixa você escolher quais preparar com y/n.

A:

Isso costuma acontecer por mudanças de final de linha (CRLF/LF) ou de permissões. Veja o 'git diff' para saber o que mudou. Configure o .gitattributes para lidar com os finais de linha.

A:

Primeiro adicione ao .gitignore os arquivos que quer excluir, depois use 'git add .'. Outra opção é adicionar os arquivos um a um ou usar padrões como 'git add *.js'.

A:

Ele diz ao Git que você pretende adicionar o arquivo depois. O arquivo passa a ser rastreado (aparece no git diff), mas o conteúdo ainda não é preparado. Útil para revisar arquivos novos antes do commit.

A:

Não, o Git só rastreia arquivos, não diretórios. A solução comum é colocar um arquivo .gitkeep ou .gitignore dentro do diretório vazio.