TRUNK-BASED DEVELOPMENT

Guia prático de Git
Branches curtas · Integração frequente · Releases controladas

A ideia em 30 segundos

TBD mantém main como linha de integração, com entregas pequenas e branches curtas. CI (Integração Contínua) compila, testa e analisa o código a cada push ou PR/MR. Release branches são opcionais e apenas estabilizam versões enquanto main evolui.

GitGraph com a main como trunk, branches curtas, releases e correções selecionadas.

GitGraph em cores para modo escuro.

01 · Clonar repositório

Este é o fluxo principal quando o projeto já existe em um servidor Git. A URL pode usar SSH ou HTTPS.

git clone <URL-DO-REMOTO>
cd nome-repo
git switch main
git pull --ff-only origin main

origin é o nome convencional do remoto. --ff-only evita criar merge automático e falha se houver divergência.

02 · Criar uma branch curta

Use uma branch para uma mudança pequena que precisa de revisão ou CI antes de chegar à trunk. Termine em horas ou poucos dias.

Nomeie a branch conforme a mudança: feat/, fix/, docs/, test/, refactor/, build/ ou chore/. O glossário explica os prefixos.

git switch -c feat/leitura-sensor
git status
git diff -- src/sensor.c include/sensor.h
git add src/sensor.c include/sensor.h
git rm src/obsolete.c
git commit -m "feat: lê sensor por I2C"

Adicione arquivos explicitamente; git rm remove o arquivo do working tree e do índice.

Para corrigir o último commit antes de publicar:

git add include/sensor.h
git commit --amend --no-edit

Boa prática

Mesmo com a linha pela metade, faça um commit ao fim do dia para não perder progresso. Se ainda não publicou esse commit, continue no dia seguinte e use --amend para atualizá-lo; ele troca o SHA. Depois de publicar, prefira um novo commit em vez de reescrever histórico compartilhado.

Publique a branch para abrir o PR/MR. A integração em main acontece depois, na plataforma remota:

git push -u origin feat/leitura-sensor

03 · Publicar e integrar PR/MR

PR (GitHub) e MR (GitLab) são pedidos de revisão na plataforma; abrir ou aprovar não integra. Após CI e aprovação conforme a política, faça o merge. São opcionais no TBD: mantenha branches e revisões curtas.

GitHub · Instalar gh

gh pr create --base main --fill
# após aprovação
gh pr merge --squash --delete-branch

GitLab · Instalar glab

glab mr create --fill
# após aprovação
glab mr merge --squash --remove-source-branch

Codeberg / Gitea · Instalar tea

tea pulls create \
  --base main \
  --head feat/exemplo \
  --title "feat: adiciona exemplo"
# após aprovação, faça o merge na interface web

Merge local (integração feita neste clone, sem PR/MR):

git switch main
git merge --no-ff feat/exemplo

Só altera o repositório local; o servidor remoto não recebe esse merge.

Atualizar × integrar

--ff-only  A---B---S  main
--no-ff   A---B---------M  main
               \       /
                C-----D    feat/exemplo

pull --ff-only atualiza main; M marca o merge --no-ff.

04 · Limpeza após PR/MR

Merge local: git branch -d. Após squash remoto, confirme o PR/MR e use git branch -D. A plataforma remove a branch remota.

git switch main
git pull --ff-only
git branch -d feat/leitura-sensor

Logo de Marcio Bulla

Marcio
Bulla

From beginner to beginner

05 · Release, tag e update intermediário

Release branch é opcional: crie perto do lançamento, somente para estabilizar. A trunk continua recebendo features; a release não recebe funcionalidades novas.

git switch main
git pull --ff-only origin main
git switch -c release/1.0
git push -u origin release/1.0
git tag -a v1.0.0 -m "Release 1.0.0"
git push origin v1.0.0

A tag deve apontar para o commit exato aprovado. Para um update 1.0.1 nascido na trunk, localize o SHA, leve a correção à release e só então crie a tag.

git switch main
git log --oneline --decorate -10
# corrija, teste e commite
git switch release/1.0
git cherry-pick <SHA>
git tag -a v1.0.1 -m "Release 1.0.1"
git push origin release/1.0 v1.0.1

Propagação controlada

cherry-pick cria outro commit, normalmente com outro SHA. Em conflito, resolva, use git add e git cherry-pick --continue; cancele com git cherry-pick --abort.

06 · Ler o histórico

Use o log para localizar o commit aprovado, entender a topologia e comparar trunk com release.

git log --oneline --decorate --graph --all
git show <SHA>
git log main..release/1.0
git diff main..release/1.0

07 · Restaurar após um problema

Para recuperar um commit antigo sem reescrever a trunk compartilhada, localize-o e crie uma branch de recuperação.

git reflog
git switch -c recovery/old-state <SHA>
git restore --source=<SHA> -- src/sensor.c
git diff --stat
git add src/sensor.c
git commit -m "fix: restaura estado estável"
git push -u origin recovery/old-state

Se o objetivo é desfazer um commit já publicado, prefira revert:

git switch main
git pull --ff-only origin main
git revert <SHA>
git push origin main

Cuidado

git revert cria um novo commit e preserva o histórico. git reset --hard pode descartar mudanças locais e não deve reescrever histórico compartilhado. Antes de trocar de estado, preserve trabalho com git stash push -m "wip".

EXTRA · Criar um repositório local

Use este fluxo quando o projeto ainda não existe como repositório Git. Depois, publique-o no remoto.

git init
git switch -c main
git add README.md
git commit -m "chore: inicia repositório"
git remote add origin <URL-DO-REMOTO>
git push -u origin main

Glossário rápido de comandos

Prefixos (branch: / · commit: :): feat funcionalidade · fix correção · docs documentação · test testes · refactor estrutura sem mudar comportamento · build build/dependências · chore manutenção e organização.

git clone — copia um repositório remoto.
git init — inicia um repositório Git local.
git remote — gerencia os endereços dos repositórios remotos.
git switch — muda de branch; -c cria uma nova.
git status — mostra o estado dos arquivos.
git diff — compara alterações ainda não commitadas.
git add — prepara alterações; não cria commit.
git rm — remove e prepara a remoção de um arquivo.
git merge — integra o histórico de outra branch.

git commit — grava no histórico o que foi preparado.
git log — lista commits; --oneline resume.
git show — exibe um commit e suas alterações.
git pull — busca e integra atualizações remotas.
git push — publica commits locais no remoto.
git fetch — busca referências sem alterar sua branch.
git tag — marca um commit com uma versão.
git cherry-pick — copia um commit para outra branch.
git revert / restore / stash — desfaz, recupera ou guarda.

Logo de Marcio Bulla

Marcio
Bulla

From beginner to beginner

Versão para impressão: baixar o PDF A4 · English (PDF) · Español (PDF)

Fontes oficiais: Trunk-Based Development: short-lived branches · PRs e revisão contínua · git-merge · git-pull · git-rebase · git-push · git-revert