Nesta aula

Guia independente, não oficial

Git e GitHub

Salve versões do seu projeto e guarde o histórico em um repositório privado no GitHub. Você vai entender cada parte, fazer o primeiro registro e aprender a repetir o processo quando o trabalho avançar.

BMAD 6.12.4 · conferido em 15/11/2026macOSClaude CodeGitHub
Etapa 01

O que é o Git e por que usar

Nesta Aula, as Fases são Entender → Preparar → Salvar → Rotina. Cada Fase reúne Etapas; dentro delas, os Passos dizem o que fazer. Pedido é o texto para colar no chat do Claude Code, com a pasta do projeto aberta. Comando é a linha para executar no terminal, a janela em que você dá instruções ao computador por texto.

Use primeiro o caminho Pelo Claude Code. A alternativa Pelo terminal permite realizar a mesma tarefa manualmente. Na Etapa 06, você também pode criar o repositório pelo site do GitHub. Escolha um caminho por tarefa para não repetir a criação.

Os Pedidos descrevem o resultado desejado. O Claude Code pode solicitar autorização para editar arquivos ou executar Comandos, conforme o modo de permissão da sessão. Leia a ação proposta e confira a pasta e o destino. Uma resposta dizendo que pretende fazer algo ainda não comprova que fez: confira o resultado de cada Passo.

Imagine uma proposta comercial que passou por várias revisões. Você quer saber o que mudou, quem mudou e qual versão foi aprovada. Renomear arquivos como “final”, “final-agora” e “final-valendo” logo fica confuso. O Git organiza esse histórico do projeto. A analogia é com um arquivo de versões identificadas: você decide quando registrar um novo marco.

O que é o Git?

Git é a ferramenta que registra versões dos arquivos do projeto no seu computador. Você pode consultar o histórico e registrar mudanças mesmo sem internet. Repositório é o conjunto que guarda esse histórico e as informações usadas pelo Git para acompanhar o projeto. Na prática desta Aula, ele fica junto da sua pasta de trabalho, em uma pasta interna chamada .git.

O que é um commit?

Commit é um registro de uma versão do projeto, acompanhado de uma mensagem. Pense em uma fotografia identificada: “cadastro de clientes concluído”. Antes de tirar essa fotografia, você seleciona as alterações que entram nela. Salvar um arquivo no editor e fazer um commit são ações diferentes; o commit usa o conteúdo que foi selecionado.

Essa seleção tem um nome: área de preparação, também chamada de staging area ou index na documentação. Imagine uma bandeja com os documentos que entrarão no próximo registro. Você pode estar mudando o cadastro e o frete ao mesmo tempo, mas preparar apenas a alteração do cadastro. O commit registra essa seleção. Se editar um arquivo depois de selecioná-lo, a edição nova só entrará quando você selecionar novamente o conteúdo.

O que é um repositório remoto?

Repositório remoto é outro repositório com o qual você troca o histórico; nesta Aula, ele fica no GitHub. GitHub é o serviço que hospeda repositórios e permite controlar quem tem acesso a eles. Pense no arquivo da empresa guardado fora do seu computador. O Git organiza as versões; o GitHub recebe o histórico que você envia.

O chamado “git remote” é o cadastro do endereço desse destino no Git. Vamos dar a ele o nome origin, um apelido para não precisar repetir o endereço inteiro. Cadastrar esse endereço ainda não envia nada.

O que é push?

Push é o envio de commits do computador para o repositório remoto. Na analogia, é entregar ao arquivo externo as versões que você já registrou. Um commit pode existir só no seu computador até você fazer esse envio. Alterações ainda não registradas em commit não entram no push.

Fig. 1 / Da pasta ao GitHub
Ver em texto
  1. Edite os arquivos na pasta do projeto.
  2. Selecione as alterações que devem entrar na versão, deixando segredos de fora.
  3. Faça um commit para registrar essa versão no computador.
  4. Faça push para enviar o histórico ao GitHub.
  5. Confira os arquivos e a identificação de repositório privado no GitHub. Esse é o resultado em destaque.

Para seguir: você entende que o commit registra no computador e o push envia ao GitHub. Agora vamos preparar os dois lados.

Etapa 02

Conferir o Git no computador

Abra no Claude Code a pasta do projeto em que você trabalhou na Aula 04 — Instalação no macOS. O objetivo é conferir a ferramenta e a identificação de quem fará os commits.

O que é a identificação do Git?

É o nome e o e-mail registrados como autoria dos commits. Essa identificação não conecta sua conta ao GitHub. Para associar os commits à sua conta, use um e-mail vinculado a ela ou o endereço de privacidade fornecido pelo GitHub.

Credencial é uma senha, chave ou outro dado que permite acessar um serviço. Ela deve ficar fora dos Pedidos e dos arquivos registrados no Git.

Pelo Claude Code

Peça ao Claude Code
Confira a pasta deste projeto e diga se ela já pertence a um repositório Git. Verifique a versão instalada do Git e se há nome e e-mail configurados para os commits. Mostre a pasta, a versão e o resultado da identificação. Não mostre credenciais e não altere configurações globais. Se faltar Git, indique a instalação oficial para macOS e me diga o que preciso fazer. Se já houver histórico ou conexão com o GitHub, explique o que existe antes de adaptar os próximos passos desta aula.

Pelo terminal

Na pasta do projeto, execute uma linha por vez:

git --version
git rev-parse --show-toplevel
git config get user.name
git config get user.email

--version mostra a versão; config get lê a configuração indicada. Se nome ou e-mail não estiver definido, a consulta pode terminar sem texto e com um código de ausência. Isso não significa que o Git precisa ser reinstalado. Vamos definir a identificação apenas neste projeto na Etapa 05.

git rev-parse --show-toplevel informa a pasta principal do repositório ao qual a pasta atual pertence. Se mostrar uma pasta acima do seu projeto, pare: você pode estar dentro de outro repositório. Se informar que não há repositório Git, esse resultado é compatível com a pasta nova que será preparada na Etapa 05. Uma falha de permissão ou outro erro precisa ser analisado; não trate qualquer erro como autorização para iniciar um repositório.

Já existe histórico? Confira-o com o Pedido e preserve-o. Se o projeto já está no GitHub, mas ainda não está neste computador, o caminho é clonar: trazer uma cópia do repositório e de seu histórico para uma nova pasta. Não comece com git init nesse caso. Depois da autenticação da Etapa 04, use este Pedido. A clonagem pelo GitHub não foi executada nesta Aula.

Peça ao Claude Code
Este projeto já existe no GitHub. Quero trazer uma cópia para este computador, preservando seu histórico. Confira o endereço do repositório, a conta e o acesso. Clone em uma pasta nova, sem sobrescrever uma pasta existente. Depois mostre a pasta criada, a linha de trabalho, os destinos e o histórico recente. Oriente em qual pasta devo continuar esta aula. Não crie outro repositório no GitHub e não envie mudanças.

Se já tem uma cópia local com alterações próprias e outra no GitHub, não clone por cima nem tente juntar as duas automaticamente. Peça uma comparação dos históricos. O caso é diferente de trazer um projeto para uma pasta vazia.

Se faltar Git, a página oficial apresenta a instalação pelas ferramentas da Apple. O Comando abaixo inicia essa instalação; siga a janela do macOS e depois repita a consulta de versão. A instalação não foi repetida no teste desta Aula.

xcode-select --install

Saída esperada — versão obtida no teste

Saída esperada
git version 2.54.0 (Apple Git-157)

Seu número de versão pode ser diferente. As leituras e gravações da identificação foram conferidas na documentação. O teste original usou uma identidade fictícia somente nos comandos de commit e reversão; a revisão verificou também a gravação local dessa autoria em uma pasta descartável. Nenhum teste alterou a configuração global de autoria.

Ao fim desta Etapa:

  • Você conferiu a pasta do projeto.
  • O Git responde com uma versão.
  • Você sabe qual nome e e-mail usará, ou sabe que ainda precisa defini-los.
Etapa 03

Criar a conta no GitHub

Opcional

Pule esta Etapa se já tem uma conta e consegue entrar nela. A conta será a dona do repositório usado no exemplo. A criação da conta foi conferida na documentação e não foi repetida no teste.

Pelo Claude Code

Peça ao Claude Code
Vou usar uma conta pessoal do GitHub para guardar este projeto em um repositório privado. Oriente minha criação de conta no site oficial, sem pedir minha senha nem códigos de verificação no chat. Se eu já tiver conta, oriente apenas a entrada nela. Diga o que devo conferir antes de voltar à aula.

Pelo site do GitHub

  1. Passo 1

    Abra Criar uma conta no GitHub (abre em nova aba) em outra aba e mantenha o guia aberto.

  2. Passo 2

    Cadastre seu e-mail, escolha um nome de usuário que consiga reconhecer depois e defina a senha no próprio site.

  3. Passo 3

    Complete as verificações solicitadas pelo GitHub. Se aparecer uma escolha de plano, o GitHub Free, o plano gratuito, atende ao exemplo de repositório privado desta Aula.

  4. Passo 4

    Confira o nome da conta em que entrou. Depois volte à aba do guia, nesta Etapa.

Não há um Comando de terminal equivalente neste percurso: o cadastro e a verificação da conta são feitos por você no site.

Ao fim desta Etapa:

  • você consegue entrar na conta correta e reconhece seu nome de usuário. Nunca cole a senha ou um código de verificação no chat.
Etapa 04

Ligar o computador ao GitHub

Agora você vai autorizar o GitHub CLI a usar sua conta. Autenticação é a confirmação de que você pode acessar essa conta. O percurso abaixo usa HTTPS, a forma de conexão protegida cujo endereço começa com https://.

Pelo Claude Code

Peça ao Claude Code
Confira se o GitHub CLI, comando gh, está instalado e mostre sua versão. Se faltar, oriente a instalação oficial para macOS. Depois verifique se há uma conta autenticada, sem revelar credenciais. Para conectar minha conta pessoal, prepare o login no github.com por HTTPS e pelo navegador. Diga quando preciso assumir a autorização. Não peça senha, chave nem código no chat. Ao terminar, confira a conta ativa e me mostre qual será usada para o repositório. Confira o protocolo configurado no CLI e como o Git usará essa autorização por HTTPS. Se já houver acesso por SSH, explique como adaptar este percurso antes de criar o repositório. Se precisar ajustar o auxiliar de credenciais, explique o alcance global desse ajuste e preserve configurações de acesso da empresa que já existirem.

Pelo terminal

  1. Passo 1 — Confira a ferramenta.

    gh --version

    Se o computador não reconhecer gh, siga a instalação oficial do GitHub CLI para macOS (abre em nova aba) ou use o Pedido acima para o Claude Code orientar o método adequado ao seu computador. Depois volte a este Passo. A instalação do CLI não foi repetida no teste.

  2. Passo 2 — Confira se já há uma conta conectada.

    gh auth status

    Se a conta correta já estiver ativa e sem erro, você pode pular o novo login do Passo 3, mas ainda precisa conferir a integração com o Git no Passo 4. gh auth status verifica a autenticação do GitHub CLI; isso, sozinho, não garante que o Git usará essa conta no envio por HTTPS. Se não estiver conectado, faça o login.

    Se aparecer outra conta e a conta pretendida já estiver autenticada no CLI, você pode trocar a conta ativa com o Comando abaixo. Substitua SEU-USUARIO e confira novamente o status. Se ela ainda não estiver autenticada, faça o login do Passo 3. A troca de conta foi conferida documentalmente e não foi executada.

    gh auth switch --hostname github.com --user SEU-USUARIO
    gh auth status
  3. Passo 3 — Entre pelo navegador.

    gh auth login --hostname github.com --git-protocol https --web

    --hostname github.com escolhe o GitHub; --git-protocol https escolhe a conexão por HTTPS; --web usa o navegador para entrar. O comando básico gh auth login também existe e faz perguntas para escolher essas opções.

    O terminal orienta a abertura do navegador. Se apresentar um código temporário, use-o apenas na página indicada pelo próprio processo. No navegador, entre na conta correta, confira a solicitação do GitHub CLI e autorize. Se houver verificação adicional, conclua no GitHub. Se aparecer a pergunta para autenticar também o Git com a conta do GitHub, escolha Sim. Depois volte ao terminal e execute novamente gh auth status.

  4. Passo 4 — Confira o método de conexão e as credenciais.

    Uma conta anteriormente autenticada pode estar configurada para outro método. Consulte:

    gh config get git_protocol --host github.com

    O percurso desta Aula usa https. Se aparecer ssh, trata-se de outro método de conexão protegida, normalmente com chaves. A criação pelo CLI usa o protocolo configurado para cadastrar o endereço remoto. Por isso, não basta preparar credenciais HTTPS e ignorar essa diferença. Use o Pedido para adaptar a Aula ao acesso existente ou, se decidiu adotar HTTPS, retome o login do Passo 3 com --git-protocol https. Essa escolha de protocolo vale para as contas do mesmo servidor no CLI. Antes de mudar, confira a configuração usada pela empresa. A consulta de protocolo foi conferida documentalmente, sem ler ou alterar a configuração pessoal neste teste.

    Se você já autorizou a integração HTTPS durante o login, siga com essa configuração. Se o CLI está autenticado, mas o Git ainda não foi preparado para usar sua credencial por HTTPS, existe este Comando:

    gh auth setup-git --hostname github.com

    Ele configura o GitHub CLI como auxiliar de credenciais, o mecanismo que fornece ao Git a autorização de acesso. Não cria repositório nem envia arquivos. Esse ajuste usa a configuração global do Git para github.com e pode afetar outros projetos do mesmo usuário. A limitação à configuração local da Etapa 05 vale para nome e e-mail de autoria; este é outro ajuste. Se o computador já usa um acesso configurado pela empresa, peça ao Claude Code que confira essa configuração antes de substituí-la. O ajuste de autenticação não foi executado nos testes.

Saída esperada — o que conferir

Na consulta de versão, obtivemos este trecho real:

Saída esperada
gh version 2.83.1 (2025-11-13)
https://github.com/cli/cli/releases/tag/v2.83.1

Depois do login, a consulta deve indicar que a conta pretendida está autenticada e ativa no github.com, sem problema de autenticação. Não há transcrição de login nesta Aula, porque essa ação não foi executada. Confira a conta, não uma frase exata de sucesso.

Ao fim desta Etapa:

  • o gh responde, a conta correta aparece ativa e você conferiu como o Git usará a autenticação por HTTPS. Ainda não criamos o repositório no GitHub.
Etapa 05

Fazer o primeiro commit

Vamos registrar a primeira versão no computador. O exemplo usa uma pequena descrição de uma loja. No seu projeto, o Pedido deve selecionar os arquivos reais depois da revisão.

Pelo Claude Code

Peça ao Claude Code
Prepare o primeiro commit deste projeto. Confira primeiro a pasta e se já existe histórico Git. Se for uma pasta nova, inicie o Git com a linha principal chamada main. Se já houver histórico, preserve-o e explique a adaptação necessária.

Crie ou complemente o .gitignore sem apagar regras existentes. Exclua .env, .env.* e arquivos de chaves ou credenciais identificados no projeto. Revise os arquivos e o conteúdo que será incluído, sem exibir valores secretos. Se algum segredo já tiver sido registrado, interrompa antes de enviar qualquer coisa e explique o problema.

Confira minha identificação de autor. Se faltar, peça somente o nome e o e-mail de autoria e configure apenas este projeto. Não mude a configuração global.

Selecione explicitamente os arquivos do projeto que passaram pela revisão, confira a seleção e faça o primeiro commit com uma mensagem clara. Não envie ao GitHub ainda. Mostre o identificador do commit, a lista de arquivos incluídos e o resultado de git status. Diga o que ficou de fora.

Pelo terminal

  1. Passo 1 — Inicie o repositório novo.

    Execute na pasta do projeto, depois de conferir que ela não pertence a outro repositório:

    git init -b main

    -b main define o nome da linha inicial. Se já houver histórico, use o Pedido para conferir o caso antes de continuar.

  2. Passo 2 — Confira a autoria.

    Se precisa defini-la, substitua os dois textos entre aspas pelos seus dados:

    git config set --local user.name "SEU NOME"
    git config set --local user.email "SEU EMAIL DE AUTORIA"

    --local grava somente a configuração deste repositório. Essas duas gravações foram verificadas na revisão em um repositório descartável, com autoria fictícia. No teste original, de onde vêm as saídas abaixo, usamos git -c user.name="Pessoa de Teste" -c user.email="teste@example.com" antes de cada commit ou reversão. Cada -c vale apenas para aquela execução. Nenhum teste mudou a identidade do projeto real ou a configuração global.

  3. Passo 3 — Prepare as exclusões.

    No editor, crie .gitignore na pasta do projeto ou acrescente estas regras ao arquivo existente, preservando as demais:

    Arquivo .gitignore
    .env
    .env.*
    *.pem
    *.key

    As duas primeiras regras cobrem .env e nomes como .env.local. As outras são uma precaução para arquivos de chaves com essas terminações. Este é um começo conservador, não uma lista completa: acrescente os caminhos de credenciais específicos do projeto.

    As regras também excluem .env.example. Se precisar guardar um modelo de configuração para orientar outra pessoa, use outro nome, como configuracao-exemplo.txt, com valores fictícios. Leia o conteúdo antes de selecionar. Um arquivo de exemplo com uma chave verdadeira continua sendo um segredo. As regras deste guia são uma escolha conservadora, não uma exigência do Git para todos os projetos.

  4. Passo 4 — Prepare o conteúdo do projeto.

    Para acompanhar o exemplo em uma pasta vazia, crie no editor um arquivo README.md, o documento de apresentação do projeto, com este conteúdo. Em um projeto existente, preserve o arquivo e os demais documentos reais.

    Arquivo README.md
    # Projeto da loja
    
    Organizar os pedidos da loja.
  5. Passo 5 — Confira antes de selecionar.

    git check-ignore -v .env .env.local
    git status --short

    O primeiro Comando mostra quais regras correspondem aos nomes consultados. O segundo lista os arquivos novos e as alterações de forma resumida. A checagem de exclusão não é uma auditoria de segredos e, por padrão, omite arquivos já acompanhados pelo Git.

  6. Passo 6 — Selecione e revise.

    No exemplo de dois arquivos:

    git add .gitignore README.md
    git diff --cached

    git add prepara o conteúdo indicado para o próximo commit. git diff --cached mostra as alterações preparadas. No seu projeto, selecione também os demais arquivos revisados, usando seus nomes; os dois nomes acima cobrem somente o exemplo. Não continue se a revisão mostrar uma credencial.

    Não confunda “li o arquivo” com “conferi a seleção”. Se você corrigiu o documento depois de git add, execute novamente o git add desse arquivo e leia outra vez git diff --cached. Caso contrário, o commit pode guardar a versão anterior à correção. O conteúdo selecionado não acompanha automaticamente suas edições posteriores.

  7. Passo 7 — Registre e confira.

    git commit -m "docs: registra o início do projeto"
    git status
    git log --oneline -5

    -m fornece a mensagem do commit. git status mostra a situação dos arquivos. git log consulta o histórico; --oneline usa uma linha por registro e -5 limita a consulta aos cinco mais recentes.

    O prefixo docs: nas mensagens desta Aula é apenas um rótulo escolhido para mudanças em documentos. O Git aceita a mensagem fornecida com -m; ele não exige esse prefixo. Se a equipe tiver uma convenção de mensagens, use a dela.

Saída esperada — copiada do teste local

Ao iniciar, o Git mostrou o caminho completo da pasta de teste. No seu computador, o caminho será outro:

Saída esperada
Initialized empty Git repository in /private/tmp/claude-501/-Users-lucassales-Projects/f72649e4-473e-4d03-959c-c34b639c3f5c/scratchpad/rascunhos/aula-05/teste/.git/

Criamos .env e .env.local com valores fictícios, sem qualquer segredo, apenas para testar a exclusão. A consulta das regras devolveu:

Saída esperada
.gitignore:1:.env	.env
.gitignore:2:.env.*	.env.local

Antes da seleção, a situação resumida mostrou apenas os dois arquivos que deveriam entrar. Os sinais ?? indicam arquivos novos ainda não acompanhados.

Saída esperada
?? .gitignore
?? README.md

O primeiro commit, executado com a identidade temporária descrita acima, devolveu:

Saída esperada
[main (root-commit) 39b86e6] docs: registra o início do projeto
 2 files changed, 7 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md

Depois, git status devolveu:

Saída esperada
On branch main
nothing to commit, working tree clean

E git log --oneline -5 mostrou:

Saída esperada
39b86e6 docs: registra o início do projeto

O trecho 39b86e6 é o identificador abreviado daquele commit; o seu será diferente. A mensagem “working tree clean” indica que a consulta não encontrou alterações pendentes a mostrar. Arquivos ignorados, como os .env fictícios deste teste, podem continuar na pasta sem aparecer nessa consulta. Ela não confirma envio ao GitHub nem certifica ausência de segredos. Se aparecerem outros arquivos pendentes no seu projeto, confira se devem entrar ou ficar de fora antes de avançar.

Ao fim desta Etapa:

  • Existe um primeiro commit no computador.
  • O .gitignore faz parte desse registro.
  • Senhas, chaves, .env e suas variações ficaram de fora.
  • Você sabe quais arquivos entraram e quais ainda estão pendentes.
Etapa 06

Criar o repositório no GitHub e enviar

Principal

Agora vamos criar o destino, cadastrar sua conexão e enviar os commits. São três ações: criar o repositório no GitHub, registrar seu endereço no Git e fazer push.

O que significa privado?

Um repositório privado restringe o acesso ao dono e às pessoas autorizadas. É a escolha padrão deste guia. A conta da empresa pode ter regras próprias de acesso; no exemplo, usamos sua conta pessoal. Privado não transforma o repositório em lugar para guardar senhas.

Conta pessoal ou organização da empresa?

Uma organização reúne pessoas e repositórios sob uma administração comum no GitHub. Cada pessoa entra com sua própria conta de usuário; a organização pode ser a dona do projeto. Se a empresa já usa uma organização, confirme com a equipe onde esse trabalho deve ficar antes de criar um repositório na sua conta. O tamanho do sistema não determina sozinho essa escolha: uma loja pequena também pode querer que o projeto fique sob a administração da empresa.

No caminho pelo site, a escolha acontece em Owner, a conta dona. Pelo CLI, o nome pode ser escrito como MINHA-ORGANIZACAO/meu-projeto, preservando as demais opções do Comando abaixo. Sua conta precisa ter permissão para criar repositórios nessa organização. Não trate falta de permissão como motivo para criar uma cópia pessoal por conta própria. Os administradores também podem definir regras de visibilidade e acesso. Esse caminho empresarial foi conferido na documentação e não foi executado.

Fig. 2 / O primeiro envio
Ver em texto
  1. Você autoriza o acesso ao GitHub no navegador, como na Etapa 04.
  2. Você pede ao Claude Code o primeiro commit sem segredos, como na Etapa 05.
  3. O Claude Code usa o Git para registrar a primeira versão local.
  4. O Git retorna a identificação do commit ao Claude Code.
  5. Você pede ao Claude Code um repositório privado e o envio.
  6. O Claude Code usa o GitHub CLI para criar o repositório privado no GitHub.
  7. O GitHub informa o endereço do repositório.
  8. O Claude Code cadastra no Git esse destino com o nome origin.
  9. O Claude Code solicita ao Git o push dos commits.
  10. O Git envia o histórico ao GitHub.
  11. Você abre o repositório no GitHub e confere os arquivos e a identificação de acesso privado.

O desenho separa as ações para você entendê-las. O Comando de criação abaixo também cadastra a conexão origin; o push continua sendo uma ação separada.

Pelo Claude Code

Escolha um nome curto para o repositório e substitua meu-projeto no Pedido.

Peça ao Claude Code
Quero guardar este projeto no GitHub em um repositório PRIVADO chamado meu-projeto. Confira a conta ativa, a pasta, o primeiro commit, a linha de trabalho atual e se já existe um destino remoto chamado origin. Confira também que não há segredos no conteúdo nem no histórico que será enviado, sem mostrar valores secretos.

Se ainda não existir esse destino e o nome estiver disponível na minha conta, crie o repositório privado, conecte a pasta a ele como origin e envie os commits da linha atual. Se encontrar um destino existente, outra conta, repositório com conteúdo ou problema de acesso, pare e explique a situação antes de mudar a conexão. Não force o envio nem sobrescreva um destino existente.

Ao terminar, mostre o endereço do repositório, a confirmação de que é privado, qual linha foi enviada e como conferir os arquivos no navegador. Mostre também o resultado da operação de envio.

Alternativa pelo terminal dentro deste caminho

Este exemplo pressupõe o repositório local novo da Etapa 05, a linha main e nenhum origin existente. Confira antes:

gh auth status
git branch --show-current
git remote -v

git branch --show-current mostra a linha atual. git remote -v lista os endereços configurados. Se aparecer um destino, confira-o antes de criar outro; se a linha não for main, veja Problemas comuns.

Substitua meu-projeto pelo nome escolhido e crie o destino privado:

gh repo create meu-projeto --private --source=. --remote=origin

--private cria privado; --source=. usa o repositório da pasta atual; --remote=origin cadastra a conexão com esse nome. Sem um dono escrito antes do nome, o CLI usa a conta autenticada. Esse Comando não leva a opção de envio automático.

Confira a privacidade e o endereço antes de enviar:

gh repo view --json nameWithOwner,isPrivate,url
git remote -v

A primeira consulta devolve dados com o dono e o nome, a privacidade e o endereço. JSON é um formato de texto que organiza informações em campos e valores. --json escolhe esse formato; os três nomes após a opção escolhem os campos. Confira que isPrivate é true e que o dono e o endereço são os pretendidos.

Depois da conferência, envie e abra o repositório:

git push -u origin main
gh repo view --web

-u guarda a associação entre sua linha main e a correspondente no destino origin. Com a configuração padrão do Git e os nomes iguais deste exemplo, isso permite usar git push nas próximas vezes. Configurações de envio da empresa podem mudar esse comportamento; a Etapa 07 explica a conferência. gh repo view --web abre o repositório no navegador.

Pelo site do GitHub

Use este caminho em vez de criar pelo CLI, caso prefira escolher as opções no navegador. O Git e a autenticação continuam necessários para enviar o histórico do computador. Este caminho também foi conferido apenas na documentação.

  1. Passo 1

    Abra Criar repositório (abre em nova aba) em outra aba. Confira o campo Owner, que é a conta dona do repositório.

  2. Passo 2

    Em Repository name, escreva o nome escolhido, como meu-projeto.

  3. Passo 3

    Selecione Private / Privado.

  4. Passo 4

    Deixe desligadas as opções para acrescentar README, .gitignore ou licença. Esses arquivos não devem criar um histórico separado no destino; vamos enviar o que você já preparou no computador.

  5. Passo 5

    Clique em Create repository. Na página seguinte, copie o endereço HTTPS do repositório.

  6. Passo 6

    Volte à aba do guia e ao chat do projeto. Use o Pedido abaixo para conectar e enviar, substituindo o endereço de exemplo.

Peça ao Claude Code
Criei um repositório privado e vazio pelo site do GitHub. O endereço HTTPS é https://github.com/SEU-USUARIO/SEU-REPOSITORIO.git. Confira que ele pertence à conta esperada e que é privado. Confira a linha local e se já existe origin, sem trocar um destino existente. Revise o histórico que será enviado para não incluir segredos. Se tudo corresponder a este projeto, conecte esse endereço como origin, envie os commits e mostre o resultado e o endereço para eu conferir no navegador. Não force o envio.

Se preferir fazer essa conexão pelo terminal, substitua os dois nomes no endereço. Execute somente se origin ainda não existir e a linha local for main:

git remote add origin https://github.com/SEU-USUARIO/SEU-REPOSITORIO.git
git remote -v

Leia o resultado e confirme o endereço. git remote add apenas cadastra o destino no computador: o repositório já precisa existir no GitHub.

Somente depois dessa conferência, envie:

git push -u origin main

Saída esperada — o que conferir

No navegador, o repositório correto deve mostrar a identificação Private / Privado, os arquivos enviados e o commit que você acabou de registrar. Na consulta pelo CLI, o campo isPrivate deve ser true. Compare a mensagem do último commit com o histórico local. Esses são critérios de conferência baseados na documentação, não uma transcrição de envio realizado neste teste.

Ao fim desta Etapa:

  • A conta e o nome do repositório estão corretos.
  • O repositório está privado.
  • O destino origin aponta para ele.
  • Os arquivos e o commit aparecem no GitHub.
  • .env, senhas e chaves ficaram fora do histórico enviado.

O que ficou guardado e o que ainda está só no computador?

O GitHub recebe o histórico enviado da linha escolhida. Arquivos ainda não registrados, arquivos ignorados e mudanças em outras linhas que você não enviou não passam a estar guardados lá só porque o push terminou. Por exemplo: um documento de requisitos registrado pode estar no GitHub; uma planilha local ignorada pode continuar existindo apenas no computador. Organize separadamente a guarda dos dados que ficaram fora do repositório.

Enviar ao GitHub já coloca o site no ar? Este percurso guarda o projeto em um repositório; ele não configura a publicação de um site. Se o repositório já estiver ligado a uma plataforma como a Vercel, que publica aplicações, um push pode acionar uma publicação automática conforme a integração e a linha escolhida. Nesse caso, conferir antes de enviar também evita publicar uma mudança ainda não aprovada. A configuração dessa integração pertence à Aula 06; não foi executada nesta Aula.

Etapa 07

Salvar e enviar no dia a dia

Repita o ciclo quando concluir uma mudança que faça sentido reconhecer depois: “organiza os pedidos da loja”, “corrige o cálculo do frete” ou “acrescenta o cadastro de clientes”. A rotina é conferir o trabalho, selecionar as alterações, registrar um commit e enviar.

Onde isso entra no BMAD?

Skill é um roteiro de trabalho que orienta a inteligência artificial, ou IA. No Claude Code, as instruções de uma skill ficam em um arquivo SKILL.md. No BMAD 6.12.4, a skill bmad-build pode encerrar uma mudança com um commit local, quando o Git está disponível e há alterações. O envio não acontece automaticamente: depois de conferir o resultado, você pede o push. Se o commit já foi feito, basta conferir e enviar; não há necessidade de criar outro sem mudanças.

O Pedido de rotina abaixo é uma instrução comum ao Claude Code. Você não precisa chamar uma skill do BMAD só para registrar e enviar trabalho que já está pronto.

Qual caminho usar antes de salvar?

A rotina do Git continua sendo conferir, registrar e enviar. O que muda é como você prepara e revisa o trabalho antes desse registro.

  • O trabalho está pronto e falta apenas guardar: use o Pedido desta Etapa. O escopo de bmad-build exclui operações de versionamento que apenas registram trabalho existente.
  • Ainda é preciso implementar uma mudança: bmad-build pode partir de uma descrição direta, como “corrigir o cálculo do frete”, ou de uma unidade de trabalho já planejada. Ao terminar, confira o commit local antes de tentar registrar novamente.
  • Existe uma especificação ou um projeto maior: uma especificação descreve o resultado esperado; um épico reúne mudanças relacionadas. O trabalho pode ser dividido em várias unidades. Cada execução de bmad-build cuida de uma unidade; não é necessário esperar todo o projeto terminar para registrar avanços coerentes. A sequência de planejamento fica para a Aula 06.
  • Você quer entender a mudança antes de enviar: use /bmad-walkthrough na conversa em que bmad-build terminou. Essa skill orienta sua leitura e sugere formas de observar o funcionamento. Ajuda a decidir entre aprovar, pedir ajustes ou discutir mais. Ela não executa o conjunto de testes do projeto nem substitui uma revisão técnica.
  • Você precisa de uma revisão técnica adicional: a skill indicada é bmad-code-review. Depois de eventuais correções, confira novamente os arquivos e commits antes de enviar.

Um nome iniciado por /, como /bmad-walkthrough, é usado no chat, como Pedido de execução da skill. Não é um Comando para o terminal.

Mesmo no caminho autônomo bmad-build-auto, quando o controle de versões está disponível, o encerramento registra localmente o trabalho revisado e não faz push. Essa skill só deve ser usada quando chamada pelo nome; não é necessária para a rotina básica desta Aula. Todos esses caminhos do BMAD foram conferidos na fonte 6.12.4 e na instalação local, mas não foram executados nesta Aula.

Pelo Claude Code

Peça ao Claude Code
Concluí e conferi esta mudança. Revise a situação do Git, os arquivos alterados e os commits que ainda precisam ser enviados. Confira se há segredos, arquivos locais ou mudanças fora desta tarefa, sem revelar valores secretos.

Se faltar registrar a mudança, selecione apenas os arquivos revisados e faça um commit com uma mensagem que explique o resultado. Se o BMAD já fez esse commit, use o registro existente.

Confira a conta, o repositório privado e o destino origin. Envie os commits da linha atual sem forçar e sem misturar trabalho de outra pessoa. Se o envio for recusado, pare e explique a causa. Mostre o commit, o resultado do envio e o endereço para eu conferir no GitHub.

Pelo terminal

Confira o que mudou e o histórico recente:

git status
git diff
git log --oneline -5

git diff mostra alterações ainda não preparadas para commit em arquivos acompanhados; arquivos novos também precisam ser lidos no editor e conferidos na lista de git status.

Se ainda falta fazer o commit, selecione os arquivos revisados. No exemplo, alteramos somente o README.md, acrescentando uma promessa de entrega no mesmo dia. Essa é uma alteração fictícia para observar o ciclo e, depois, desfazê-la:

No exercício, acrescente ao final do README.md uma linha em branco e a frase Entregar todos os pedidos no mesmo dia.. Em seu projeto real, selecione a mudança de negócio que você de fato concluiu; não acrescente essa promessa fictícia. Depois selecione o arquivo:

git add README.md
git diff --cached

Leia toda a seleção antes de registrar. Ela inclui também alterações que já estavam preparadas anteriormente; retire qualquer conteúdo fora desta mudança antes de seguir.

Passo opcional — Selecionou algo que não deveria entrar? Depois de existir o primeiro commit, o Comando abaixo retira o README.md da seleção para o próximo commit e preserva as edições no arquivo de trabalho. Troque o nome pelo arquivo que precisa retirar. Faça isso antes do novo commit, depois confira outra vez a seleção e a situação:

git restore --staged README.md
git diff --cached
git status

Mantenha --staged: sem essa opção, git restore pode alterar o arquivo de trabalho e descartar edições. Essa forma usa o último commit como referência e não é a receita para uma pasta que ainda nunca teve commit. Se encontrou o problema durante a primeira seleção da Etapa 05, pare antes de registrar e peça ao Claude Code para retirar apenas o arquivo indevido, preservando seu conteúdo. A retirada de seleção depois do primeiro commit foi testada em pasta descartável.

Se retirou o README.md apenas para praticar e quer continuar o exercício da entrega no mesmo dia, selecione-o novamente com git add README.md e confira git diff --cached antes do próximo commit. Se o retirou porque ele realmente não pertence à mudança, deixe-o fora e registre somente o que foi aprovado.

Se a seleção corresponder ao que você conferiu, faça o commit:

git commit -m "docs: registra entrega no mesmo dia"

Troque o arquivo e a mensagem para descrever a sua mudança. Se o BMAD já criou o commit e não há outra alteração, pule os blocos de seleção, retirada de seleção e criação de commit.

Após conferir o destino configurado na Etapa 06, envie e consulte a situação:

git push
git status

O git push simples segue as configurações de envio. No percurso desta Aula, com a configuração padrão e a associação criada com -u, ele envia a main para origin. Uma configuração diferente, como outro destino preferencial, pode mudar isso. Se o projeto usa o destino origin e a linha main já conferidos, você pode explicitar ambos com git push origin main. Para outra linha, confira seu nome e a política da equipe antes de adaptar. Nenhum envio ao GitHub foi executado nos testes.

Trabalho individual, equipe e mudanças simultâneas

Em um projeto individual simples, esta Aula usa uma linha, main, para tornar o ciclo visível. Se outras pessoas ou agentes trabalham ao mesmo tempo, combinem como separar e revisar as mudanças. Um caminho documentado pelo GitHub é criar uma linha para a mudança, registrar nela, enviá-la e abrir uma pull request: um pedido de revisão e integração ao projeto. Depois da revisão, a integração recebe o nome de merge.

Nesse caminho, você envia a linha da mudança; não usa automaticamente git push origin main. O repositório pode exigir revisões ou verificações antes da integração. Uma recusa pode ser uma regra de proteção funcionando, mesmo que sua conta esteja corretamente autenticada. Use a política da empresa e peça ao Claude Code que identifique as regras do projeto. Esse fluxo colaborativo não foi executado nesta Aula.

Peça ao Claude Code
Este projeto tem trabalho simultâneo ou revisão obrigatória. Confira a pasta efetiva, a linha atual, os destinos e as regras do repositório. Explique qual linha deve receber esta mudança e como será revisada antes da integração. Preserve alterações de outras tarefas. Não envie direto para main se o fluxo exigir uma linha separada e uma pull request. Mostre os commits que pertencem a esta mudança e os passos que ainda dependem de revisão.

Saída esperada — segundo commit do teste local

Depois de acrescentar a promessa ao arquivo e registrá-la, obtivemos:

Saída esperada
[main ca6f0e3] docs: registra entrega no mesmo dia
 1 file changed, 2 insertions(+)

O histórico consultado com git log --oneline -5 ficou assim:

Saída esperada
ca6f0e3 docs: registra entrega no mesmo dia
39b86e6 docs: registra o início do projeto

São duas versões locais, com a mais recente em cima. Nenhuma delas foi enviada pelo teste. Na sua rotina, a conferência termina quando o commit enviado aparece também no repositório privado.

Ao fim desta Etapa:

  • você sabe repetir a revisão, o commit e o push; também sabe que o commit feito pelo BMAD pode estar aguardando seu pedido de envio.
Etapa 08

Voltar atrás

Opcional

Às vezes a mudança foi registrada, mas não deveria continuar valendo. No exemplo, a loja percebe que não pode prometer todas as entregas no mesmo dia. Vamos desfazer essa última mudança mantendo o registro do que aconteceu.

O que é revert?

Revert é a criação de um novo commit que desfaz o efeito de outro. Pense no estorno de um lançamento: o registro anterior continua no histórico, e um novo registro corrige seu efeito. HEAD é a referência à versão em que você está trabalhando; neste percurso simples, é o último commit da linha atual.

Pelo Claude Code

Peça ao Claude Code
Quero desfazer a última mudança registrada neste projeto, preservando o histórico. Confira git status e os últimos commits. Mostre qual é o último commit e quais alterações ele contém. Se houver alterações pendentes, união de linhas de trabalho, segredo no histórico ou se o alvo for o primeiro commit de preparação, pare e explique o cuidado necessário.

Se for a última mudança comum e não houver essas pendências, crie um novo commit que reverta seu efeito. Use a mensagem automática da reversão. Confira o resultado nos arquivos e no histórico. Não envie ainda: primeiro quero conferir o resultado. Mostre o commit criado e a situação final do Git.

Pelo terminal

  1. Passo 1 — Confira a situação e o alvo.

    git status
    git log --oneline -5
    git show HEAD

    Continue somente depois de confirmar que não há alterações pendentes e que o primeiro registro da lista é a mudança que você quer desfazer.

    git show HEAD permite ler a mensagem e as alterações do último commit. Confira o conteúdo, não apenas uma mensagem curta como “ajustes”. Se a alteração indesejada estiver em um commit anterior, HEAD apontará para outro alvo: pare e peça a identificação do registro correto.

  2. Passo 2 — Faça a reversão.

    A documentação do BMAD 6.12.4 cita literalmente git revert HEAD. No terminal, essa forma pode abrir um editor para a mensagem. Para usar a mensagem automática e evitar essa janela, execute:

    git revert --no-edit HEAD

    --no-edit impede a abertura do editor; o resultado continua sendo um novo commit de reversão. Foi essa forma, com nome e e-mail temporários, que rodamos no teste.

  3. Passo 3 — Confira o resultado.

    git log --oneline -5
    git status

    Leia também o arquivo alterado ou confira o comportamento do projeto. Depois de confirmar a correção, se o repositório estiver conectado como na Etapa 06, envie o novo registro com git push. A reversão também precisa ser enviada para aparecer no GitHub. Esse envio não foi testado.

Saída esperada — reversão executada no teste

Saída esperada
[main cd853c8] Revert "docs: registra entrega no mesmo dia"
 Date: Sun Nov 15 13:42:44 2026 -0300
 1 file changed, 2 deletions(-)

O histórico passou a ter três registros:

Saída esperada
cd853c8 Revert "docs: registra entrega no mesmo dia"
ca6f0e3 docs: registra entrega no mesmo dia
39b86e6 docs: registra o início do projeto

E git status confirmou:

Saída esperada
On branch main
nothing to commit, working tree clean

O README.md voltou ao conteúdo anterior à promessa de entrega, e o .gitignore permaneceu no projeto. Os identificadores e a data acima pertencem ao teste; no seu projeto serão outros.

Ao fim desta Etapa:

  • você sabe localizar o último commit, desfazer seu efeito com um novo registro e enviar a correção depois de conferir.

E se o que quero desfazer estiver em outra situação?

  • Só selecionou o arquivo e ainda não fez commit: volte à retirada de seleção da Etapa 07. Você pode deixar o conteúdo no computador e decidir depois se ele deve entrar em outro registro.
  • Editou, mas ainda não registrou: o Git não tem um commit dessa edição para reverter. Peça ao Claude Code que mostre a diferença e preserve uma cópia antes de descartar qualquer coisa. Uma edição nunca registrada pode não ser recuperável pelo Git depois de descartada.
  • O commit já foi enviado: a reversão mantém o registro anterior e cria uma correção que também precisa ser enviada. Em equipe, a correção deve seguir a mesma revisão e integração das outras mudanças.
  • O commit mistura uma mudança boa e outra ruim: reverter o commit inteiro pode retirar as duas. Peça uma correção focada no comportamento indesejado e confira o resultado antes de registrá-la. Isso é uma decisão sobre o conteúdo da correção; o efeito de revert é desfazer as mudanças do commit escolhido.
  • O alvo é uma integração de linhas: um commit de merge tem mais de um antecedente. A reversão precisa definir qual caminho será a referência e pode afetar integrações futuras. O Comando simples desta Aula não cobre essa escolha. Peça uma análise do histórico; não copie uma opção adicional sem entender qual mudança deseja preservar.

Essas alternativas explicam quando mudar de caminho. A revisão testou a retirada de seleção e a reversão de um commit comum; descarte de edições, reversão parcial e reversão de merge não foram executados.

Ajuda

Problemas comuns

  1. O envio foi recusado. O que fazer?

    Uma causa possível é o GitHub já ter mudanças que ainda não estão no computador. Nesse caso, o Git pode recusar o envio para preservar o trabalho existente. Também pode haver conta incorreta ou falta de permissão. Copie a mensagem de erro, retirando qualquer credencial, e peça ao Claude Code para verificar conta, destino e diferenças entre os históricos. Não force o envio.

    Peça ao Claude Code
    O envio ao GitHub foi recusado. Analise a mensagem, a conta ativa, o destino e os históricos local e remoto. Explique a causa e como preservar o trabalho dos dois lados. Não force o envio, não apague histórico e não troque o destino sem explicar a diferença encontrada. Mostre o próximo passo seguro para este caso.

    Se o erro for diferença de histórico, primeiro traga as informações do destino para poder compará-las. Fetch é buscar os registros remotos, sem integrar automaticamente as mudanças aos arquivos da linha em que você está trabalhando. No percurso main e origin desta Aula, depois de confirmar o endereço, execute:

    git fetch origin
    git log --oneline origin/main..HEAD
    git log --oneline HEAD..origin/main

    origin/main é a referência local à main do destino, atualizada pela busca. A primeira consulta lista commits da linha atual que ainda não estão nessa referência; a segunda lista os que estão nela e faltam na linha atual. Os dois pontos separam os lados da comparação. Essas consultas não têm o limite de cinco registros: permitem conferir o conjunto pendente. Elas pressupõem que origin/main já exista e que esta seja a linha usada no projeto.

    • Só a primeira lista tem commits: há trabalho local ainda não presente na referência consultada. Confira todos esses commits antes de tentar enviar; o push pode levar mais de uma mudança pendente.
    • Só a segunda lista tem commits: há trabalho remoto a trazer para sua linha. Com os arquivos locais sem alterações pendentes e os commits remotos revisados, a atualização pode ser feita pelo caminho abaixo.
    • As duas listas têm commits: os históricos divergiram. É preciso decidir como integrar as duas sequências, respeitando o trabalho de todos. Use o Pedido de diagnóstico; não force o envio.
    • As duas listas estão vazias: os commits coincidem com a referência obtida na busca. Se o envio ainda falhar, investigue acesso, regras do repositório ou outra causa indicada na mensagem. Essa comparação não comprova que arquivos fora de commits foram enviados.

    Quando apenas falta trazer os commits remotos, use esta atualização restrita, somente na main e com o destino origin já conferidos:

    git pull --ff-only origin main

    Pull é buscar e integrar alterações. A opção --ff-only permite a atualização apenas quando basta avançar sua linha para os commits já existentes no destino, sem criar um commit de integração. Se houver divergência, ela recusa a integração. Depois confira os arquivos e o funcionamento do projeto. A busca, as comparações e os dois resultados de --ff-only — avanço permitido e divergência recusada — foram testados entre repositórios locais descartáveis. Não foram testados contra o GitHub.

    Se o destino foi criado pelo site com um README próprio, ele pode ter um histórico inicial separado do seu. Esse caso não se resolve apenas repetindo push ou a atualização acima. Preserve os dois lados e peça uma análise; é por isso que a Etapa 06 pede criar o destino vazio.

  2. Pediu senha no terminal. Qual senha usar?

    Não digite a senha da sua conta como senha de uma operação Git por HTTPS: o GitHub deixou de aceitar essa forma de autenticação. Volte à Etapa 04, confira gh auth status e a integração de credenciais do Passo 4. Se faltar autenticação, refaça o login pelo navegador; se o CLI já estiver autenticado, investigue o acesso do Git antes de repetir o login. Não copie uma chave de acesso para o chat para resolver a mensagem.

  3. Um segredo foi enviado. Basta apagar o arquivo?

    Não. Apagar o arquivo atual, acrescentar uma regra ao .gitignore ou fazer revert não elimina o dado das versões anteriores. Revogue a credencial exposta e gere outra no serviço responsável. Depois avalie se também é necessário retirar o conteúdo do histórico. Para uma credencial, revogar ou substituir pode ser suficiente para interromper seu uso indevido; reescrever o histórico não é uma etapa automática para todos os casos. Outros dados confidenciais podem exigir uma limpeza específica. Siga a orientação oficial, considerando cópias e pessoas com acesso. Repositório privado continua exigindo esse cuidado. Não publique o segredo no chat ao pedir ajuda; informe apenas o tipo de dado e o arquivo afetado.

    Se o segredo entrou em um commit que ainda não foi enviado, interrompa o push. Um novo commit apagando o arquivo não remove o dado do commit anterior. Peça a correção do histórico local antes do primeiro envio e confira o conjunto completo que será enviado. Esses procedimentos de remoção de dados não foram executados nesta Aula.

  4. O branch tem outro nome. Preciso trocar para main?

    Não automaticamente. Consulte git branch --show-current. Se o projeto já tinha uma linha chamada, por exemplo, master, peça ao Claude Code que ajuste o envio ao nome e à política daquele projeto. O main desta Aula foi uma escolha explícita na criação, não uma garantia sobre todos os repositórios. Se a consulta não mostrar nome algum, pare e peça a análise antes de enviar.

  5. Já existe um origin. Posso cadastrar outro por cima?

    Primeiro consulte git remote -v e confira de quem é o endereço. origin pode já ser o destino correto ou apontar para outro projeto. Não apague nem substitua esse cadastro sem entender o caso. Se o destino certo já existe, o caminho é conferir acesso, privacidade e histórico antes de enviar.

  6. A reversão parou com um conflito. Como sair?

    Conflito é uma situação em que o Git não consegue conciliar as alterações automaticamente. Pare e peça ao Claude Code que explique os arquivos envolvidos. Se a intenção for cancelar uma reversão ainda em andamento e voltar ao estado anterior a ela, existe git revert --abort. Esse cancelamento não serve para desfazer uma reversão já concluída. O caminho com conflito e seu cancelamento foram conferidos na documentação, mas não foram executados no teste.

  7. “Não há nada para registrar” significa que está no GitHub?

    Não. Significa que o Git não encontrou uma nova alteração para aquele commit. Um commit anterior ainda pode estar só no computador. Confira o histórico, o resultado do push e a página do repositório.

  8. O Git não reconheceu config get ou config set. Preciso começar de novo?

    Não. Pode ser uma versão anterior à sintaxe usada nesta Aula. Confira git --version. A documentação também mantém as formas antigas: git config --get user.name e git config --get user.email para consultar; git config --local user.name "SEU NOME" e git config --local user.email "SEU EMAIL DE AUTORIA" para definir. A gravação continua exigindo que o repositório já exista. Essas formas foram verificadas com o Git do teste; não executamos a Aula em versões antigas. Se o erro for outro, use a mensagem para diagnosticar antes de modificar a configuração.

Fontes desta aula