git add e git commit: como salvar alterações do jeito certo

No Git não existe botão «salvar». As alterações são registradas em dois passos: primeiro o git add escolhe quais mudanças entram no próximo snapshot, depois o git commit grava esse snapshot no histórico. A área intermediária entre os dois se chama índice, ou staging area. É justamente ela que muita gente passa anos sem entender — e é ela que dá sentido aos commits.

Os três estados de um arquivo: diretório de trabalho, índice e histórico

Toda alteração percorre três áreas:

1. Diretório de trabalho — você edita o arquivo no editor.
2. Índice (stage) — o git add coloca a versão atual do arquivo no rascunho do próximo commit.
3. Histórico — o git commit transforma o conteúdo do índice em um commit com autor, data e mensagem.

Uma analogia útil é uma encomenda. O diretório de trabalho é o quarto com as coisas, o índice é a caixa aberta onde você coloca o que quer enviar e o commit é o pacote lacrado e etiquetado. Você decide o que vai na caixa e não precisa mandar tudo de uma vez.

Para que serve o índice

Imagine: em uma hora você corrigiu um bug na autenticação, aproveitou para arrumar um erro de digitação no README e começou uma funcionalidade nova. Sem índice, tudo isso cairia num único commit «diversos». Com o índice, você faz três commits separados, cada um fácil de entender, revisar e, se necessário, reverter sem afetar o resto.

git status: o que mudou e o que está preparado

Antes de cada add e commit, vale olhar o git status. É o comando mais seguro do Git — ele não altera nada.

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/auth.js

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        src/profile.js

• Changes to be committed — já está no índice e vai entrar no commit;
• Changes not staged — foi alterado, mas não adicionado;
• Untracked files — arquivos novos que o Git ainda não conhece.

O formato curto é mais prático quando há muitos arquivos:

$ git status -s
M  src/auth.js
 M README.md
?? src/profile.js

A primeira coluna é o estado no índice, a segunda é no diretório de trabalho. M à esquerda significa «alterado e adicionado», à direita — «alterado, não adicionado»; ?? — não rastreado.

git add: como adicionar alterações ao índice

Um sinônimo de git add é git stage: é o mesmo comando, daí o termo «stage» e o jargão «stagear» um arquivo.

git add -p: adicionar só parte de um arquivo

É o recurso mais subestimado. Se um arquivo mistura duas alterações diferentes, o git add -p mostra cada trecho e pergunta se deve adicioná-lo:

$ git add -p src/auth.js
@@ -12,7 +12,7 @@ function login(user) {
-  if (user.password = input) {
+  if (user.password === input) {
(1/2) Stage this hunk [y,n,q,a,d,s,e,?]?

y — adicionar, n — pular, s — dividir o trecho em pedaços menores, q — sair. Assim, um único arquivo rende dois commits bem organizados.

Como conferir o que exatamente vai para o commit

git diff            # alterações que AINDA NÃO estão no índice
git diff --staged   # o que já está no índice e vai entrar no commit

Uma confusão frequente: depois do git add, o git diff simples não mostra nada. Isso não quer dizer que as alterações sumiram — elas estão no índice; use git diff --staged (sinônimo de --cached).

Como desfazer o git add (tirar um arquivo do índice)

git restore --staged file.js

As alterações no arquivo continuam lá; ele só deixa de estar preparado para o commit. Em versões antigas do Git se usava git reset HEAD file.js — que continua funcionando.

git commit: registrando as alterações

git commit -m "Corrigir verificação de senha no login"

[main 3f2a9c1] Corrigir verificação de senha no login
 1 file changed, 1 insertion(+), 1 deletion(-)

A resposta traz a branch, o hash curto do novo commit e as estatísticas. Só o conteúdo do índice entra no commit. Se depois do git add você mexeu de novo no arquivo, as novas alterações não entram no commit até você adicioná-las outra vez.

Flags úteis do git commit

Se o editor padrão for o Vim e você ficou preso nele: escreva a mensagem, aperte Esc, digite :wq e Enter. Para trocar o editor: git config --global core.editor "code --wait" ou nano.

Como escrever uma boa mensagem de commit

A mensagem vai ser lida seis meses depois, quando alguém estiver procurando a origem de um bug. Ela deve responder «o quê e por quê», e não «o que eu fiz hoje».

• primeira linha com até 50–72 caracteres, com a essência da mudança;
• no imperativo ou em tom neutro: «Adicionar validação de e-mail», «Fix login redirect»;
• se necessário, uma linha em branco e os detalhes: por que assim, quais são as limitações;
• um commit — uma mudança lógica.

Ruim: fix, ajustes, wip, asdf. Bom: Corrigir erro do carrinho com lista de produtos vazia. Muitas equipes usam o formato Conventional Commits: feat: ..., fix: ..., docs: ....

git commit --amend: como corrigir o último commit

Erro de digitação na mensagem ou esqueceu de adicionar um arquivo — não precisa criar um commit novo «esqueci o arquivo». Para isso existe o amend.

Corrigir a mensagem

git commit --amend -m "Corrigir verificação de senha no login"

Adicionar um arquivo esquecido

git add forgotten.js
git commit --amend --no-edit

A flag --no-edit mantém a mensagem anterior.

O que é importante saber sobre o amend

O --amend não «edita» o commit: ele cria um novo, com outro hash, e substitui o antigo. Enquanto o commit existe só na sua máquina, é seguro. Se você já fez git push, depois do amend o push normal será rejeitado e você terá de usar git push --force-with-lease. Em branches compartilhadas, onde outras pessoas trabalham, não faça isso: você reescreveria o histórico sobre o qual elas já estão construindo.

Se o amend foi feito por engano, o commit antigo pode ser encontrado no git reflog e restaurado com git reset --soft HEAD@{1}.

Erros comuns

«nothing to commit, working tree clean»

Não há alterações — tudo já foi commitado, ou você está editando o arquivo em outra pasta. Confira o git status e o caminho do projeto.

«no changes added to commit»

Os arquivos foram alterados, mas não foram adicionados ao índice. Rode git add ou use git commit -am para arquivos já rastreados.

«Please tell me who you are»

Nome e e-mail não estão configurados. Rode uma vez git config --global user.name "Nome" e git config --global user.email "email".

Commitou coisa demais

Se o commit ainda não foi enviado, desfaça-o mantendo as alterações no índice: git reset --soft HEAD~1. Depois tire o que sobra com git restore --staged e faça o commit de novo. Se um segredo foi parar no commit, considere-o comprometido e gere outro.

git add . adicionou lixo

Configure o .gitignore com antecedência e confira o git status antes de commitar. Um arquivo já rastreado só deixa de ser rastreado depois de git rm --cached arquivo.

O que um commit é de verdade

O commit não guarda a diferença em relação à versão anterior, e sim um snapshot do projeto inteiro: referência para a árvore de arquivos, referência para o commit pai, autor, data e mensagem. Arquivos sem alteração não são copiados — o Git aponta para objetos já salvos, por isso o histórico ocupa pouco espaço.

O hash do commit (por exemplo, 3f2a9c1) é calculado a partir de todo esse conteúdo. Mude uma letra da mensagem e o hash será outro. É por isso que --amend e rebase criam commits novos em vez de editar os antigos, e é por isso que um histórico reescrito entra em conflito com as cópias dos colegas.

Para ver o histórico de forma resumida:

git log --oneline --graph -10

Cada linha é um commit; se as mensagens do seu histórico fazem sentido sem abrir o diff, você está no caminho certo.

O ciclo de trabalho do dia a dia

git status                 # o que mudou
git diff                   # ver as alterações
git add -p                 # escolher o que interessa
git diff --staged          # conferir o que vai para o commit
git commit -m "Descrição clara"
git log --oneline -5       # confirmar que o commit está lá
git push                   # enviar para o servidor

O commit salva as alterações só localmente. Para que elas cheguem ao GitHub ou a outro servidor, é preciso um git push.

Resumo

O git add monta o próximo snapshot no índice, o git status e o git diff --staged mostram o que vai entrar nele, e o git commit grava o snapshot no histórico. Faça commits pequenos e lógicos, com mensagens claras, e use git commit --amend para pequenas correções no último commit — antes do push. O índice e o fluxo em dois passos add → commit são trabalhados na prática no curso de Git.