git add

Descrição

O comando git add adiciona alterações do diretório de trabalho para a área de preparação (também chamada de index). Com ele, você indica ao Git quais alterações de arquivo deseja incluir no próximo commit. O git add não salva nada no histórico por si só — ele apenas marca as alterações como prontas. Para registrá-las de fato, você executa git commit em seguida. Para verificar o que está ou não preparado a qualquer momento, use git status.

Esta página aborda o que o git add faz, as três "áreas" do Git entre as quais ele atua, suas opções mais úteis e os modos interativo e de edição de patches para preparar alterações trecho por trecho.

As três áreas

Cada alteração em um projeto Git passa por três áreas:

• Diretório de trabalho — os arquivos que você edita diretamente no disco.
• Área de preparação (index) — um instantâneo do que entrará no próximo commit.
• Repositório — o histórico de commits, gravado pelo git commit.

O git add move as alterações do diretório de trabalho para a área de preparação. O git commit então grava tudo o que estiver preparado no repositório. Esse fluxo em duas etapas é o que permite transformar um diretório de trabalho bagunçado em commits limpos e focados.

Por que preparar alterações?

Em muitos sistemas de controle de versão, o commit captura tudo o que foi alterado. O Git deliberadamente adiciona a área de preparação no meio para que você possa decidir exatamente o que cada commit contém. Isso é útil quando você editou várias coisas não relacionadas de uma vez: você pode preparar e confirmar uma alteração lógica, depois preparar e confirmar a próxima, mantendo seu histórico legível.

Como a preparação captura um instantâneo no momento em que é executada, o git add deve ser executado novamente sempre que você fizer novas edições que queira incluir. Se você preparar um arquivo e continuar editando-o, as edições posteriores permanecerão não preparadas até que você execute git add novamente.

Opções comuns

Preparar um único arquivo para o próximo commit:

git add <file>

Preparar todas as alterações dentro de um diretório (recursivamente, incluindo novos arquivos):

git add <directory>

Preparar todas as alterações no repositório inteiro — arquivos novos, modificados e excluídos:

git add -A

Preparar alterações apenas em arquivos já rastreados, incluindo exclusões, mas ignorar arquivos novos não rastreados:

git add -u

Preparar alterações de forma interativa, escolhendo partes dos arquivos trecho por trecho:

git add -p

git add . vs git add -A vs git add -u

Esses três comandos são fáceis de confundir, por isso vale ser preciso:

No Git moderno, git add . e git add -A ambos preparam exclusões; a diferença é apenas o escopo do caminho. Use -u quando você criou arquivos temporários que não quer confirmar e prefere não listá-los no .gitignore.

Exemplos de git add

Você pode executar esses comandos em qualquer repositório Git. Comece verificando o estado atual com git status, depois prepare e confirme.

Preparar um novo arquivo

git add hello.py

Preparar vários arquivos específicos de uma vez

git add hello.py utils.py README.md

Preparar tudo e confirmar com uma mensagem

git add -A
git commit -m "Add greeting script"

Ver o que está preparado antes de confirmar

git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   hello.py

Para retirar um arquivo da área de preparação sem perder suas edições, use git restore --staged (ou, em versões mais antigas do Git, git reset):

git restore --staged hello.py

Modo interativo

Executar git add -p (ou escolher a opção de patch em git add -i) inicia uma sessão de preparação interativa. O Git mostra um hunk — um bloco de linhas alteradas — por vez e solicita um comando. As respostas mais comuns são:

• y - preparar este hunk
• n - não preparar este hunk
• q - sair; não preparar este hunk nem os restantes
• a - preparar este hunk e todos os hunks posteriores no arquivo
• d - não preparar este hunk nem nenhum hunk posterior no arquivo
• g - selecionar um hunk para ir até ele
• / - procurar um hunk que corresponda à expressão regular fornecida
• j - deixar este hunk indeciso, ir para o próximo hunk indeciso
• J - deixar este hunk indeciso, ir para o próximo hunk
• k - deixar este hunk indeciso, ir para o hunk indeciso anterior
• K - deixar este hunk indeciso, ir para o hunk anterior
• s - dividir o hunk atual em hunks menores
• e - editar manualmente o hunk atual
• ? - exibir ajuda

Dividir (s) é especialmente útil: se o Git apresentar duas edições não relacionadas como um único hunk, s as separa para que você possa preparar apenas a parte desejada. Esta é a forma cotidiana de construir um commit limpo a partir de um arquivo com alterações mistas.

Edição de patches

Chamar git add -e ou selecionar e no seletor interativo de trechos abre um patch no seu editor. Após sair do editor, a saída é aplicada ao index. Você pode fazer alterações arbitrárias no patch, mas algumas edições podem resultar em saídas complexas ou até tornar o patch inaplicável. Se quiser cancelar a operação inteiramente, simplesmente exclua todas as linhas do patch. Aqui estão alguns elementos comuns que você pode ver em um patch e quais operações de edição fazem sentido para eles.

Linhas que começam com + representam conteúdo adicionado. Você pode excluí-las para evitar preparar linhas adicionadas.

Linhas que começam com - representam conteúdo removido. Para evitar preparar a exclusão delas, converta o - em um espaço ( ).

O conteúdo modificado é mostrado com linhas - (excluindo o conteúdo antigo) seguidas de linhas + (adicionando o conteúdo substituto). Para evitar preparar a modificação, converta as linhas - em espaços e remova as linhas +. Observe que modificar apenas metade do par pode causar alterações confusas no index.

Armadilhas comuns

• A preparação é um instantâneo, não um link dinâmico. Se você executar git add em um arquivo e editá-lo novamente, apenas a versão anterior estará preparada. Execute git add mais uma vez para incluir as novas edições — git status mostrará o mesmo arquivo tanto em "Changes to be committed" quanto em "Changes not staged for commit."
• git add não exclui arquivos por você. Ele prepara exclusões de arquivos já rastreados (com -A ou -u), mas para excluir um arquivo do disco e preparar essa exclusão em uma única etapa, use git rm.
• Arquivos ignorados continuam ignorados. Padrões no .gitignore não são preparados pelo git add .. Para forçar a adição de um arquivo ignorado, passe git add -f <file>.
• Nada é permanente ainda. A preparação é totalmente reversível. Use git restore --staged <file> para desfazer a preparação antes de confirmar.

Prática