GitHub para quem não escreve o código

Se você nunca usou o GitHub, ignore como ele costuma ser descrito. Não é uma rede social para programadores, você não está ali para ler o código de ninguém, e os quadradinhos verdes não são um placar que você precisa preencher.

É um sistema de salvamento com histórico, hospedado em algum lugar que não é o seu notebook. É isso.

Para um vibe coder, ele ganha o lugar dele por um motivo específico. Em algum momento — não talvez, em algum momento — uma sessão vai reescrever algo que já funcionava. Vai refatorar um arquivo de que você gostava, apagar uma função que decidiu que não era usada, ou corrigir um bug introduzindo dois em silêncio. Sem commits, aquele trabalho se foi e sua única recuperação é descrever tudo de novo, de memória, para um modelo que esqueceu a conversa. Com commits, a recuperação é uma frase.

Este guia é tudo de que você precisa para isso, e nada de que você não precisa.

Git e GitHub não são a mesma coisa

Vale dez segundos, porque misturar os dois é o que deixa todo o resto confuso.

Git é um programa no seu computador. Ele registra versões de uma pasta. Funciona sem internet, sem conta e sem site, e é o que faz todo o trabalho de fato.

GitHub é um site que guarda uma cópia de um repositório Git e acrescenta o que um site pode acrescentar: uma página para navegar nele, um lugar para outras pessoas, automação que roda quando você envia.

Então quando o seu agente “commita”, isso é o Git, local, instantâneo. Quando ele faz “push”, isso é a cópia viajando para o GitHub. É por isso que você consegue trabalhar num avião e por isso que um commit não é um backup até ter sido enviado.

As alternativas — GitLab, Bitbucket, Codeberg — são o mesmo Git por baixo com outro site por cima. Nada neste guia muda se você escolher uma delas.

As sete palavras que cobrem quase tudo

Elas ficam em inglês porque é assim que você vai vê-las no GitHub e no terminal:

Mais duas que você vai ver e pode quase sempre ignorar: origin é o apelido padrão para “a cópia que está no GitHub”, e main é o nome padrão do branch principal.

Preciso aprender comandos de Git?

Não, e esta é a parte que ninguém conta para quem está começando. Você precisa de três frases para dizer ao seu agente, e ele roda os comandos.

• Faz o commit disso com uma mensagem clara.
• O que mudou desde o último commit?
• Desfaz tudo desde o último commit.

Essa é a interface inteira do seu primeiro mês. O que você precisa mesmo é entender o que essas três coisas significam, que é para isso que serve o resto desta página — porque a falha típica não é digitar o comando errado, é pedir o tipo errado de desfazer.

Se você prefere botões a frases, o GitHub Desktop é gratuito, mostra os arquivos alterados como um diff visual e transforma commit e push em dois cliques. Muita gente que publica produtos reais nunca usa o terminal para o Git.

Onde seu código fica enquanto você trabalha

As mensagens do Git falam de arquivos “staged”, “tracked” e “untracked”, e nada disso faz sentido até você saber que existem três lugares onde uma mudança pode estar:

A área de staging é a parte que parece inútil no começo. O propósito dela é escolher: doze arquivos mudaram, quatro pertencem a este commit, então você marca esses quatro. Como vibe coder você vai commitar quase sempre tudo de uma vez — mas precisa saber que o staging existe, senão “changes not staged for commit” é uma mensagem de erro sobre nada.

git status é o comando de “onde eu estou”, e é o que vale a pena você mesmo saber ler. Ele diz em qual branch você está, o que mudou, o que está em staging e se você está à frente ou atrás do GitHub. Quando algo está confuso, é a primeira coisa a olhar, e é completamente seguro: não muda nada.

O primeiro arquivo que importa: .gitignore

Antes do seu primeiro push, antes de qualquer outra coisa: o .gitignore é uma lista de arquivos que o Git nunca deve registrar.

No mínimo, ele contém:

.env
.env.local
node_modules/
.DS_Store
dist/

O .env é o que importa. É ali que ficam suas API keys, e aquela única linha é o que impede que elas sejam publicadas na primeira vez que você enviar. Repositórios públicos são varridos continuamente por gente procurando exatamente isso, e uma chave vazada é encontrada em minutos, não em dias.

Peça isso explicitamente na configuração inicial — adicione um .gitignore apropriado para esta stack e garanta que o .env está nele — e depois confira com seus próprios olhos que o .env está listado. É uma verificação de trinta segundos que evita o erro caro mais comum de quem começa.

Deixe o repositório privado por padrão. Público é uma decisão deliberada de publicar, e é muito mais fácil tornar público depois um repositório privado do que despublicar alguma coisa, inclusive tudo que está no histórico dela.

Como leio um diff sem ler código?

Um diff é o que mudou, mostrado linha por linha. Linhas verdes com + foram adicionadas, linhas vermelhas com - foram removidas, linhas cinzas são contexto sem alteração. Você não precisa entender o código para tirar valor real dali:

• Qual é o tamanho? Doze linhas alteradas para um pedido pequeno é normal. Quatrocentas é um sinal para parar e perguntar o que mais ele fez.
• Quais arquivos? Se você pediu uma mudança de cor e um arquivo com auth, migration ou schema no nome está na lista, esse é o momento de perguntar por quê.
• Alguma coisa apagada que você não pediu para apagar? Blocos longos de vermelho merecem uma pergunta.

Essa é a habilidade inteira, e é a maior parte do que uma revisão de código entrega num projeto solo. Me mostra o diff e explica em português claro o que a mudança de cada arquivo faz é um bom hábito antes de cada commit.

O que faz uma mensagem de commit valer a pena?

O único trabalho dela é ajudar o você do futuro a achar um momento no tempo. “Update” e “fixes” falham nisso; seis delas em sequência são indistinguíveis.

Escreva qual é o estado, não o que você fez: tela de login funciona, validação ainda não feita. Seis semanas depois, essa mensagem é o que permite dizer “volta para quando o login funcionava” e significar algo preciso.

Faça o commit quando algo funciona, não no fim do dia. O fim do dia é um ponto de salvamento para oito horas de decisões. Todo estado que funciona é um lugar ao qual você pode voltar.

Quando eu de fato preciso de um branch?

Como vibe coder solo, menos vezes do que os tutoriais dão a entender. Você precisa de um quando está prestes a tentar algo de que pode se arrepender: uma refatoração grande, uma troca arriscada de dependência, um experimento do qual você só está meio convencido.

O motivo é que o desfazer fica de graça. Você está no experiment, dá errado, você volta para o main e apaga o branch. Nada para desatar, nada para reverter, nenhuma discussão com o agente sobre o que ele mudou.

No momento em que mais alguém toca no repositório, isso deixa de ser opcional e passa a ser um branch por pedaço de trabalho — que é onde o vibe coding fica genuinamente mais difícil, e um problema diferente deste.

Como eu desfaço alguma coisa?

A seção mais importante desta página. Existem quatro tipos de desfazer, e pedir o errado é como as pessoas perdem trabalho tentando salvá-lo.

1. Você tem mudanças sem commit e quer elas fora.

git restore .

Tudo desde o último commit desaparece. Este é o do dia a dia: a sessão deu errado, nada valia a pena guardar, recomeça do último estado bom.

2. Você commitou, mas não enviou, e quer o commit fora.

git reset --soft HEAD~1   # desfaz o commit, mantém as mudanças
git reset --hard HEAD~1   # desfaz o commit e as mudanças

--soft é para “commit certo, mensagem errada, momento errado”. --hard é para “aquela direção inteira estava errada”.

3. Você já enviou, e outras pessoas (ou um deploy) têm aquilo.

git revert <commit>

Isso faz um commit novo que desfaz o antigo. É o seguro, porque acrescenta ao histórico em vez de reescrevê-lo, e nada do que outra pessoa já tem discorda do que você tem.

4. Você acha que perdeu algo para sempre.

git reflog

O Git mantém um registro privado de cada posição em que o seu branch esteve por cerca de noventa dias, incluindo commits que você “apagou” e branches que removeu. Quase nada some de verdade. Este é o que se busca depois de um --hard do qual você se arrependeu ou de um force-push que comeu a sua tarde — e vale saber que ele existe justamente porque o momento em que você precisa dele é o momento em que você está em pânico.

O que é um conflito de merge, e quem resolve?

Dois branches mudaram as mesmas linhas. O Git não vai adivinhar qual versão vence, então marca o trecho em disputa no arquivo com <<<<<<< e >>>>>>> e para.

Nada está quebrado e nada foi perdido. As duas versões estão ali; alguém tem que escolher.

Agentes são bons nisso, com uma condição: conte para eles para que cada mudança servia. A decisão é sobre intenção, não sintaxe — este lado é a lógica nova de preços, aquele lado é a correção do bug de ontem, mantenha os dois comportamentos recebe uma resolução correta. “Resolve o conflito” recebe um cara ou coroa.

O que acontece se eu commitar uma API key?

Rotacione. Agora. Vá até o serviço, revogue a chave, emita uma nova.

Apagar o arquivo num commit posterior não faz nada, porque a chave continua ali no histórico, onde qualquer um consegue ler. Num repositório público, presuma que ela foi varrida em minutos: isso é automatizado em escala.

O GitHub ajuda em dois pontos, e vale ligar os dois. O secret scanning percebe formatos de chave conhecidos no seu repositório e avisa você. A push protection vai além e bloqueia o envio antes de o segredo chegar a aterrissar. Nenhum dos dois cobre todo formato, então o .gitignore continua sendo a defesa de verdade.

Limpar a chave do histórico depois é possível e chato. Também é secundário: uma vez rotacionada a chave, a que está no histórico é uma string morta.

O que mais é o GitHub, além de armazenamento?

Coisas que você vai encontrar, em uma linha cada:

• Issues — uma lista de pendências anexada ao projeto. Serve para anotações solo, embora um board de verdade seja melhor assim que o trabalho ganha forma.
• Actions — automação que roda no push. É assim que os testes rodam e que os deploys disparam. Você vai encontrar na primeira vez que conectar um host.
• Releases e tags — um nome fixado a um commit específico. v1-launch é um marcador dizendo esta versão estava boa, e não custa nada.
• Pages — hospedagem estática gratuita direto de um repositório. Serve para uma landing, não para nada com backend.
• Fork — sua própria cópia do repositório de outra pessoa. Relevante quando você quer mudar o projeto open source de alguém.
• Dependabot — abre pull requests quando uma dependência tem uma correção de segurança. Gratuito, vale deixar ligado.
• Codespaces — um ambiente de desenvolvimento completo no navegador. Útil quando você quer trabalhar de uma máquina que não tem nada instalado.

Coisas que vão te confundir exatamente uma vez

Cada uma delas produz um momento de alarme genuíno, e cada uma é inofensiva depois que você viu uma vez.

“You are in ‘detached HEAD’ state.” Você olhou um commit antigo e agora está em cima dele em vez de em um branch. Commits feitos aqui não pertencem a nada e são fáceis de perder. git switch main traz você de volta. Nada está quebrado.

Seu repositório contém outro repositório. Um agente rodou git init dentro de uma pasta que já estava em um repo, normalmente enquanto montava alguma coisa. O GitHub então mostra uma pasta que você não consegue abrir e que não contém nada. A correção é apagar a pasta .git interna — e a pista é um commit que adiciona um diretório mas nenhum dos arquivos dentro dele.

Um arquivo é grande demais para enviar. O GitHub rejeita arquivos individuais acima de 100 MB, e um vídeo, um dump de banco de dados ou um node_modules que escapou do .gitignore vão bater nisso. A armadilha é que remover o arquivo não conserta o envio, porque ele continua no histórico — o commit que o adicionou precisa ser desfeito. É bem mais fácil prevenir: confira o .gitignore antes do primeiro push.

Suas duas máquinas discordam. Você commitou no notebook, enviou, e depois commitou no desktop sem dar pull. O Git vai recusar o segundo envio. git pull primeiro, resolva o que ele perguntar, e então envie. O hábito que evita isso por completo é dar pull no começo de uma sessão, não no fim.

O agente commitou como outra pessoa. Commits carregam o nome e o e-mail da sua configuração local do Git, que numa máquina nova pode estar em branco ou errada. Vale configurar uma vez, ou o seu histórico fica assinado por “unknown”.

Truques que se pagam sozinhos

• Faça o commit antes de cada sessão com o agente, não depois. O commit não é um registro do que você fez, é o ponto de salvamento que você está prestes a arriscar. Dez segundos, e ele converte todo desastre em git restore .
• Peça o diff antes de aceitar. Me mostra o que você mudou e por quê pega o extra prestativo que você não queria, que é a falha mais comum a sobreviver até produção.
• Um branch por experimento, e apagar é o desfazer. Mais barato que qualquer revert.
• git stash quando o agente reclamar de árvore suja. Ele guarda no bolso o seu trabalho sem commit; git stash pop devolve. Melhor que commitar lixo para se destravar.
• --force-with-lease, nunca --force puro. Os dois reescrevem o que está no GitHub. O primeiro recusa se outra pessoa enviou nesse meio-tempo; o segundo sobrescreve sem perguntar.
• Proteja a main assim que algo real estiver nela. A proteção de branch do GitHub pode exigir um pull request antes do merge, o que torna “o agente enviou direto para a main às 2 da manhã” estruturalmente impossível em vez de meramente desencorajado.
• Marque com tag a versão que funcionou. Antes de uma mudança grande, v-works não custa nada e é trivialmente encontrável, ao contrário de um hash de commit que você nunca vai reconhecer.
• Faça squash no merge. Catorze commits de “wip”, “fix”, “agora vai” viram uma entrada com significado, e o seu histórico continua legível por um humano — e pelo próximo agente que o ler.
• Lembre que o reflog existe antes de precisar dele. No momento em que você precisar, não vai estar em estado de descobri-lo.

O que fazer no primeiro dia

1. Crie a conta. Deixe o primeiro repositório privado.
2. Coloque o .gitignore no lugar com o .env nele, e confira com seus próprios olhos.
3. Peça ao agente para fazer o primeiro commit e enviar. Olhe o repositório no GitHub e veja seus arquivos ali.
4. E então, toda vez que algo funcionar: faz o commit disso com uma mensagem clara.

Essa é a prática inteira. Todo o resto desta página está aqui para o dia em que algo der errado — e o motivo para ler agora é que o dia em que algo dá errado é um péssimo dia para estar aprendendo de qual tipo de desfazer você precisa.

O resto da configuração em que isto se encaixa — o modelo, o host, a stack, as salvaguardas — são seis decisões, e o controle de versão é a que todas as outras presumem que você já tem.