Git e GitHub

Entenda controle de versão, configure seu ambiente, domine os comandos essenciais e aprenda a padronizar seus commits com Conventional Commits

Introdução

Antes de escrever qualquer comando, é importante entender a diferença entre as duas ferramentas que usaremos ao longo deste guia:

Git
Sistema de controle de versão para monitorar alterações no código localmente
GitHub
Plataforma na nuvem que hospeda repositórios e facilita a colaboração entre múltiplos desenvolvedores

Conceitos Básicos

Dois conceitos são centrais para entender por que o Git existe e por que ele é tão valioso no desenvolvimento de software:

Versionamento
Prática de gerenciar diferentes estágios de um projeto, permitindo recuperar versões anteriores e evitar perda de dados
Controle de versão
Cria um histórico detalhado que identifica quem alterou o quê e quando, garantindo a integridade do código-fonte

Instalação

Debian / Ubuntu

Bash 
sudo apt-get install git

Configuração

Usuário único

Bash 
# Usuário
git config --global user.name "Seu Nome"

# E-mail
git config --global user.email "[email protected]"

# Gerar chave SSH
ssh-keygen -t ed25519 -C "[email protected]"
# Pressione Enter nas perguntas para usar os valores padrão

# Exibir a chave pública para copiar e colar no GitHub
cat ~/.ssh/id_ed25519.pub

# GitHub > Settings > SSH and GPG keys > New SSH key > Cole e salve

Múltiplos usuários (pessoal + trabalho)

Quando se utiliza o mesmo computador para projetos pessoais e profissionais, é necessário configurar identidades SSH separadas para cada conta GitHub.

1. Gerar as chaves SSH

Bash — Conta pessoal 
ssh-keygen -t ed25519 -C "[email protected]"
# Quando solicitado o arquivo, digite: id_pessoal

# Generate public/private ed25519 key pair.
# Enter file in which to save the key (/c/Users/pessoal.ssh/id_ed25519): id_pessoal
# Enter passphrase (empty for no passphrase):

# Pressione Enter para deixar a passphrase em branco (ou defina uma)
Bash — Conta de trabalho 
ssh-keygen -t ed25519 -C "[email protected]"
# Quando solicitado o arquivo, digite: id_trabalho

# Generate public/private ed25519 key pair.
# Enter file in which to save the key (/c/Users/pessoal.ssh/id_ed25519): id_trabalho
# Enter passphrase (empty for no passphrase):

# Pressione Enter para deixar a passphrase em branco (ou defina uma)

2. Adicionar as chaves ao SSH agent

Bash 
eval "$(ssh-agent -s)"
# Agent pid XXXX

ssh-add ~/.ssh/id_pessoal
# Identity added: id_pessoal

ssh-add ~/.ssh/id_trabalho
# Identity added: id_trabalho

3. Adicionar as chaves públicas ao GitHub

Bash 
# Copie cada chave e adicione em:
# GitHub > Settings > SSH and GPG keys > New SSH key > Cole e salve

cat ~/.ssh/id_pessoal.pub
cat ~/.ssh/id_trabalho.pub

4. Criar o arquivo de configuração SSH

Crie ou edite o arquivo ~/.ssh/config:

~/.ssh/config 
# Conta pessoal
Host github.com-pessoal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_pessoal

# Conta de trabalho
Host github.com-trabalho
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_trabalho

5. Testar as conexões

Bash 
ssh -T [email protected]
# Hi <usuario-pessoal>! You've successfully authenticated...

ssh -T [email protected]
# Hi <usuario-trabalho>! You've successfully authenticated...

6. Clonar repositórios usando o host correto

Bash 
git clone [email protected]:usuario-pessoal/repositorio.git
git clone [email protected]:usuario-trabalho/repositorio.git

Criando um Repositório

Para criar um novo repositório no GitHub, acesse Repositories > New e preencha as opções abaixo:

Repository name
Nome simples e direto (ex: meu-projeto, my-project)
Description
Breve descrição do projeto (opcional, mas recomendado)
Visibility
Public (recomendado) ou Private
Add a README file
Apresenta o projeto na página inicial (recomendado)
Add .gitignore
Escolha o template da linguagem do projeto. Gerador: toptal.com/developers/gitignore
Choose a license
Define como seu código pode ser usado por outros. Referência: GitHub Docs — Licenças

.gitignore

O arquivo .gitignore instrui o Git a não rastrear determinados arquivos ou pastas, como dependências, variáveis de ambiente e arquivos gerados automaticamente.

.gitignore 
# Ignorar uma pasta inteira (ex: dependências do Node)
node_modules/

# Ignorar arquivos de configuração sensíveis (senhas)
.env

# Ignorar todos os arquivos que terminam com .log
*.log

# Ignorar arquivos específicos do sistema operacional
Thumbs.db
.DS_Store

# "!" Abre a exceção para o arquivo específico
!config_fixo.log

Comandos

Iniciando uma área de trabalho

git clone 
# Clonar um repositório existente
git clone https://github.com/usuario/projeto.git
git init 
# Criar um repositório novo do zero
git init meu-projeto

Trabalhando com mudanças

git add 
# Adicionar arquivos para o próximo commit
git add index.html        # um arquivo específico
git add .                 # todos os arquivos alterados
git mv 
# Mover ou renomear um arquivo
git mv velho-nome.txt novo-nome.txt
git restore 
# Descartar alterações não commitadas
git restore arquivo.txt   # desfaz mudanças no arquivo
git rm 
# Remover um arquivo do projeto e do índice
git rm arquivo.txt

Examinando histórico e estado

git bisect 
# Encontrar qual commit introduziu um bug
git bisect start

git bisect bad            # commit atual tem o bug
git bisect good v1.0      # essa versão estava OK

# O Git navega automaticamente; você testa e repete:
git bisect good           # ou: git bisect bad
git diff 
# Ver o que mudou
git diff                  # mudanças ainda não adicionadas
git diff HEAD~1           # comparar com o commit anterior
git grep 
# Buscar texto no código
git grep "função login"
git log 
# Ver histórico de commits
git log --oneline         # resumido, uma linha por commit
git show 
# Ver detalhes de um commit
git show a3f5c1b          # hash do commit
git status 
# Ver estado atual dos arquivos
git status

Gerenciando histórico e branches

git branch 
# Criar ou listar branches
git branch                # lista todas as branches
git branch nova-feature   # cria uma branch nova
git commit 
# Salvar as mudanças no histórico
git commit -m "Adiciona página de login"
git merge 
# Unir uma branch na atual
git merge nova-feature
git rebase 
# Reaplicar commits sobre outra base
git rebase main           # reaplica commits em cima da main
git reset 
# Desfazer commits ou unstage arquivos
git reset HEAD~1          # desfaz o último commit (mantém arquivos)
git switch 
# Trocar de branch
git switch nova-feature
git switch -c outra-branch  # cria e já troca
git tag 
# Marcar uma versão
git tag v1.0.0

Colaborando

git fetch 
# Baixar atualizações sem aplicar
git fetch origin
git pull 
# Baixar e já aplicar atualizações
git pull origin main
git push 
# Enviar commits para o repositório remoto
git push origin main

Padronização de Commits

O que é Conventional Commits?

É uma convenção leve para mensagens de commit que segue um formato estruturado. Facilita a leitura do histórico, a geração automática de changelogs e o versionamento semântico (SemVer).

Especificação oficial: conventionalcommits.org

Estrutura do Commit

Formato 
<tipo>[escopo opcional]: <descrição>

[corpo opcional]

[rodapé(s) opcional(is)]

Tipos Principais

Tipos do Conventional Commits
Tipo Quando usar
feat Nova funcionalidade
fix Correção de bug
docs Alterações apenas em documentação
style Formatação, ponto e vírgula, espaços (sem mudança de lógica)
refactor Refatoração de código (sem bug fix nem feature)
perf Melhoria de performance
test Adição ou correção de testes
build Mudanças no sistema de build ou dependências externas
ci Mudanças em arquivos e scripts de CI/CD
chore Tarefas de manutenção que não alteram src ou testes
revert Reverte um commit anterior

Exemplos Práticos

Commits simples (sem escopo) 
feat: adiciona autenticação via OAuth2
fix: corrige cálculo de desconto no carrinho
docs: atualiza README com instruções de instalação
style: aplica formatação do prettier nos arquivos ts
refactor: extrai lógica de validação para módulo separado
perf: substitui loop por operação de batch no banco
test: adiciona testes unitários para UserService
chore: atualiza dependências para versões mais recentes
Commits com escopo 
feat(auth): adiciona suporte a login com Google
fix(cart): corrige arredondamento de valores decimais
docs(api): documenta endpoint de criação de pedidos
test(payment): cobre cenários de falha na integração com Stripe
refactor(database): migra queries para uso de ORM
ci(github-actions): adiciona job de lint no pipeline de PR
build(docker): otimiza imagem para reduzir tamanho final
Commit com corpo 
fix(auth): corrige expiração incorreta do token JWT

O token estava sendo gerado com timezone UTC+0 fixo,
causando expiração antecipada para usuários em fusos
negativos. Agora usa o timestamp do servidor corretamente.
Breaking Change 
feat(api)!: remove endpoint legado /v1/users

BREAKING CHANGE: O endpoint /v1/users foi removido.
Migre para /v2/users que retorna o mesmo contrato
com campos adicionais de paginação.
Múltiplos rodapés 
fix(billing): corrige cobrança duplicada em planos anuais

Detectado em produção via alertas do Datadog. A cobrança
ocorria duas vezes quando o webhook de confirmação do
gateway era recebido com delay superior a 30s.

Closes #482
Reviewed-by: Maria Silva
Co-authored-by: João Souza <[email protected]>
Revert 
revert: feat(auth): adiciona suporte a login com Google

Refs: abc1234

Revertido por instabilidade no fluxo de callback em
ambientes com proxy reverso. Será retomado na próxima sprint.

Boas Práticas Avançadas

  1. Um commit = uma responsabilidade: cada commit deve representar uma única mudança lógica. Se você se pegar escrevendo "e" na descrição, provavelmente são dois commits.
  2. Commits atômicos: o repositório deve compilar e os testes devem passar em qualquer commit do histórico. Isso é essencial para git bisect funcionar bem.
  3. Prefira git commit --amend a commits de correção: se você ainda não fez push, emende o commit ao invés de criar um fix: corrige typo do commit anterior.
git commit --amend 
git add .
git commit --amend --no-edit   # mantém a mensagem atual
git commit --amend             # abre editor para alterar mensagem

Use git rebase -i para limpar o histórico antes do merge — agrupe, reordene ou edite commits de uma branch antes de abri-la para revisão.

git rebase -i 
git rebase -i HEAD~5   # abre editor para os últimos 5 commits
Ações disponíveis no editor interativo
Ação Efeito
pick Mantém o commit
reword Mantém, mas edita a mensagem
edit Para e permite emendas
squash Junta com o commit anterior
fixup Como squash, mas descarta a mensagem
drop Remove o commit