Cheatsheet Git

O Git é um sistema de controlo de versões distribuído, criado por Linus Torvalds em 2005 (o mesmo criador do Linux) para substituir o BitKeeper no desenvolvimento do kernel.

Principais características:

• Distribuído: cada utilizador tem o repositório completo localmente, com todo o histórico.
• Rápido: operações como commit, branch e merge são feitas localmente, sem rede.
• Seguro: cada alteração é protegida por um hash SHA-1, o que torna o histórico praticamente inviolável.

git config --list
git config --global --list
git config user.name
git config --show-origin --list

O --list mostra todas as definições ativas (sistema, global e local). Para ver só um valor, passa a chave, por exemplo user.name. O --show-origin indica de que ficheiro (.gitconfig) vem cada definição — útil para resolver conflitos de configuração.

git init
git init meu-projeto
git init --bare repositorio.git

O git init cria a pasta oculta .git com toda a estrutura interna do repositório. Com um nome de pasta, cria também o diretório. A flag --bare cria um repositório sem working directory, usado em servidores.

Atenção: se já existir uma pasta .git, não executes isto de novo — podes corromper o histórico.

O Git lê a configuração em três níveis, do mais geral para o mais específico:

• --system: todo o computador (ficheiro /etc/gitconfig).
• --global: o teu utilizador (ficheiro ~/.gitconfig).
• --local: só o repositório atual (ficheiro .git/config) — é o nível por omissão.

O nível mais específico ganha sempre: uma definição --local sobrepõe-se à --global, que se sobrepõe à --system.

git clone https://github.com/utilizador/repositorio.git
git clone https://github.com/utilizador/repositorio.git pasta-local
git clone --depth 1 https://github.com/utilizador/repositorio.git
git clone -b develop https://github.com/utilizador/repositorio.git

O git clone copia tudo do repositório remoto (histórico, branches, tags) para a tua máquina e cria automaticamente a ligação ao origin. O --depth 1 faz um clone superficial (só o último commit, mais rápido). O -b clona diretamente uma branch específica.

git --version
git help config
git config --help

O git --version mostra a versão instalada — útil para confirmar se tens funcionalidades recentes como o git switch (Git 2.23+). O git help comando abre o manual completo de qualquer comando.

git config --global user.name "O Teu Nome"
git config --global user.email "email@exemplo.com"
git config --global init.defaultBranch main
git config --global core.editor "code --wait"

Define a identidade que o Git regista em cada commit. A flag --global aplica a todo o utilizador; sem ela, a configuração fica apenas no repositório atual. O init.defaultBranch define o nome da branch inicial e o core.editor o editor usado nas mensagens.

git status
git status -s
git status --ignored

O comando mais usado no Git. Mostra a branch atual, os ficheiros alterados, os que estão em staging (prontos para o próximo commit) e os não rastreados. O -s dá uma versão curta e o --ignored inclui ficheiros ignorados pelo .gitignore.

git commit -am "Atualizar dependências"

O -a adiciona automaticamente todos os ficheiros já rastreados e modificados, saltando o git add. Atenção: ficheiros novos (não rastreados) não são incluídos — esses continuam a precisar de git add.

node_modules/
.env
*.log
dist/
!dist/.gitkeep

O ficheiro .gitignore diz ao Git que ficheiros não devem ser rastreados: dependências (node_modules/), segredos (.env), logs e artefactos de build. O ! nega um padrão (inclui de volta). Ficheiros já versionados não são ignorados — usa git rm --cached primeiro.

git add ficheiro.php
git add .
git add -p
git add *.js

O staging é a "sala de espera" antes do commit: escolhes exatamente o que entra. O git add . adiciona tudo; o -p (patch) deixa rever e aprovar parte a parte de cada ficheiro. Nunca faças commits às cegas: git status + git add dá-te controlo total.

git diff
git diff --staged
git diff main..feature
git diff HEAD~3

O git diff mostra as alterações fora do staging; com --staged mostra o que já está preparado para o próximo commit. Podes comparar duas branches com main..feature ou o teu trabalho contra um commit antigo com HEAD~3.

Cada ficheiro no Git vive num de três estados:

• Working directory: os ficheiros como estão no teu disco, com alterações por guardar.
• Staging area: o que preparaste com git add para o próximo commit.
• Repositório: o que já foi gravado com git commit.

O fluxo normal é sempre: editar → git add → git commit.

git commit -m "Mensagem clara e útil"

Um commit é um ponto guardado na linha temporal do projeto. Boas mensagens poupam horas de debugging: descreve o que foi feito e porquê, não apenas "fix". Regra de ouro: título curto e direto, até 50 caracteres.

git rm ficheiro.txt
git rm -r pasta/
git rm --cached ficheiro.txt

O git rm apaga o ficheiro do repositório e do disco. O --cached remove só do repositório, mantendo o ficheiro local — a forma correta de deixar de versionar algo que deve passar para o .gitignore.

git commit -m "Adicionar validação de email" -m "Impede registos com emails inválidos. Valida formato e domínio."

O primeiro -m é o título; o segundo fica como corpo da mensagem. O Git lê a primeira linha como título — deve ser curto e direto. Usa o corpo para explicar o contexto e o porquê da alteração.

git mv antigo.php novo.php
git mv ficheiro.php pasta/

O git mv renomeia ou move ficheiros mantendo o histórico de alterações associado. É o equivalente a fazer mv + git add num só passo, e o Git regista a operação como rename.

git log
git log -5
git log --stat

Mostra o histórico de commits da branch atual: IDs (SHA-1), autores, datas e mensagens. O -5 limita aos últimos cinco e o --stat acrescenta um resumo dos ficheiros alterados em cada commit.

git log -S "nomeDaFuncao"
git log -S "nomeDaFuncao" --oneline

O -S (pickaxe) encontra os commits que adicionaram ou removeram aquele texto no código — não apenas na mensagem. É a ferramenta certa para descobrir em que commit uma função ou bug foi introduzido.

git bisect start
git bisect bad
git bisect good v1.0
git bisect reset

O git bisect faz uma pesquisa binária no histórico: marcas um commit bom (good) e um mau (bad), e o Git vai testando os do meio até encontrar o commit exato que introduziu o bug. O git bisect reset devolve-te à branch original.

git log --oneline
git log --oneline -10

Mostra cada commit numa só linha, com o ID abreviado e a mensagem. É a forma mais rápida de ter uma visão geral e limpa do histórico do projeto.

git show
git show a1b2c3d
git show a1b2c3d --stat

Sem argumentos, mostra o último commit com o diff completo. Com um ID (basta o prefixo, ex.: a1b2c3d), mostra esse commit. Também funciona para ver o conteúdo de uma tag ou de um ficheiro noutro ponto do histórico.

git shortlog -sn
git shortlog -sn --since="1 year ago"

O git shortlog -sn agrupa os commits por autor com a contagem, ordenada do mais ativo para o menos. Ideal para relatórios rápidos de atividade da equipa.

git log --oneline --graph --all
git log --graph --pretty=format:'%h %d %s (%an)' --all

Combina --oneline, --graph (desenho ASCII das ramificações) e --all (todas as branches, não só a atual). Permite visualizar rapidamente a estrutura do projeto e como as branches se interligam nos merges.

git blame ficheiro.php
git blame -L 10,20 ficheiro.php
git blame -w ficheiro.php

O git blame mostra, linha a linha, o último commit e o autor que tocou em cada uma. O -L 10,20 limita ao intervalo de linhas e o -w ignora alterações de espaços. Útil para perceber a origem de código estranho — sem julgamentos!

git log --author="Nome"
git log --grep="palavra"
git log --since="2 weeks ago"
git log -- app/Models/

Filtra commits por autor (--author), por texto na mensagem (--grep), por data (--since/--until) ou por caminho de ficheiro. Essencial para encontrar "quem fez isto" ou "quando apareceu aquele bug".

git reflog
git reflog --date=iso
git checkout a1b2c3d

O reflog regista todas as movimentações do HEAD — mesmo commits "apagados" por um reset. É a rede de segurança do Git: encontra o ID do commit perdido e recupera-o com git checkout ou git reset. Nada está verdadeiramente perdido.

git branch feature/nome-da-branch

As branches são "universos paralelos" do teu código: a main é a linha temporal oficial e as restantes são ramificações onde trabalhas sem estragar nada. Convenções mais usadas: feature/ (novas funcionalidades), bugfix/ (bugs do dia a dia), hotfix/ (urgências em produção) e release/ (preparar versões).

git checkout -b feature/login

Cria a branch feature/login e muda logo para ela. Combina git branch (criar) e git checkout (mudar) num só passo — a forma mais rápida de começar uma funcionalidade nova.

git branch -D nome
git push origin --delete nome

O -D apaga a branch mesmo sem merge — atenção, o trabalho não integrado perde-se (embora o reflog ainda o guarde por uns tempos). O push origin --delete remove a branch do repositório remoto.

git branch
git branch -v
git branch --merged

Lista as branches locais e marca com * aquela em que estás. O -v mostra o último commit de cada uma e o --merged lista as que já estão integradas na branch atual — boas candidatas a apagar.

git switch nome-da-branch
git switch -c feature/login
git switch -

O git switch (Git 2.23+) faz só a parte do checkout que muda de branch, sem os efeitos secundários perigosos (como restaurar ficheiros). O -c cria e muda, e o - volta à branch anterior.

git branch -a
git branch -r

O -a mostra todas as branches (locais e remotas); o -r só as remotas (ex.: origin/main). As remotas são "fotografias" do servidor, atualizadas com git fetch.

git branch -m novo-nome
git branch -m nome-antigo novo-nome

O -m renomeia a branch atual (ou a indicada). Se a branch já estava no remoto, terás de apagar a remota antiga com git push origin --delete e fazer push da nova com -u.

git checkout nome-da-branch

Atualiza os ficheiros do working directory para refletirem a branch escolhida e move o ponteiro HEAD para ela. O Git bloqueia a troca se houver alterações não guardadas que entrem em conflito — usa git stash nesses casos.

git branch -d nome

O git branch -d apaga a branch só se já tiver sido integrada (merged) noutra. É a forma segura de limpar branches que já não são precisas, sem risco de perder trabalho.

git checkout main
git merge bugfix/nome-da-branch

O git merge cria um merge commit que junta o trabalho da branch à atual, preservando o histórico tal como aconteceu. Ótimo para equipas, porque regista quando e como cada funcionalidade foi integrada.

git merge --abort
git rebase --abort

Se um merge ou rebase correu mal (conflitos impossíveis, por exemplo), o --abort cancela a operação e devolve tudo ao estado anterior, sem danos. É o "botão de pânico" oficial.

git merge --no-ff feature/login

Por omissão, se a branch não divergiu, o Git só avança o ponteiro (fast-forward) e o merge fica invisível no histórico. O --no-ff força a criação do merge commit, mantendo visível que aquela funcionalidade existiu como branch.

<<<<<<< HEAD
o teu código
=======
código da outra branch
>>>>>>> nome-da-branch

Quando o Git não consegue juntar duas versões da mesma linha, marca o ficheiro com <<<<<<< HEAD, ======= e >>>>>>>. Passos: abre o ficheiro, escolhe o que manter (podes misturar ou reescrever), remove as marcas, guarda e finaliza com git add . e git commit.

git checkout main
git merge --squash feature/login
git commit -m "Adicionar login"

O --squash junta todos os commits da branch num único conjunto de alterações, que commitas manualmente. Ideal para transformar branches com dezenas de commits "wip" num único commit limpo na main.

git cherry-pick a1b2c3d
git cherry-pick a1b2c3d b2c3d4e
git cherry-pick --no-commit a1b2c3d

Aplica um commit específico (pelo ID) à branch atual, sem fazer merge da branch inteira. Útil para levar uma correção urgente para a release sem arrastar o resto da feature. O --no-commit aplica as alterações sem commitar.

git checkout feature
git rebase main

"Teletransporta" os teus commits como se tivessem sido feitos depois dos últimos da main, ficando o histórico linear e limpo. Perigoso em branches partilhadas no remoto: reescrever histórico alheio causa conflitos e perda de trabalho.

Merge: preserva o histórico real, cria merge commits, seguro em branches partilhadas. Usa quando trabalhas em equipa no remoto.

Rebase: reescreve o histórico para ficar linear, mais limpo de ler. Usa apenas em branches locais e pessoais, antes de fazer push.

Regra de ouro: nunca faças rebase em branches públicas que outros também usam.

git remote add origin https://github.com/utilizador/repo.git

Adiciona o repositório remoto com o nome origin (convenção para o remoto principal). A partir daqui podes usar git push e git fetch para sincronizar com o GitHub, GitLab ou Bitbucket.

git pull
git pull origin main

Traz as alterações do remoto e aplica-as automaticamente à tua branch atual. É o equivalente a git fetch + git merge. Se houver divergências, pode gerar conflitos ou um merge commit.

git push -u origin nome-da-branch

Envia a branch e liga-a à remota (define o upstream). A partir daí, git push e git pull funcionam sem argumentos — o Git já sabe de onde vem e para onde vai o código.

git remote
git remote -v
git remote show origin

Lista os remotos configurados. O -v mostra os URLs de fetch e push (permite confirmar se usas HTTPS ou SSH). O git remote show origin dá o detalhe completo: branches rastreadas e estado de sincronização.

git fetch: descarrega as novidades mas não toca no teu código — seguro para espreitar. git pull: descarrega e integra logo na tua branch. Na dúvida, usa fetch primeiro, vê o que mudou com git log origin/main, e só depois decide entre merge ou rebase.

git push --force-with-lease
git push --force

Depois de um rebase, o histórico diverge do remoto e o push normal é recusado. O --force sobrepõe o remoto cega e perigosamente; o --force-with-lease só avança se ninguém tiver enviado commits novos — usa sempre este.

git remote rename origin upstream
git remote remove upstream

O rename muda o nome de um remoto (e atualiza todas as referências). O remove apaga a ligação — os teus commits locais não são afetados, só deixas de poder fazer push/pull para esse endereço.

git pull --rebase
git config --global pull.rebase true

Traz as alterações do remoto e reaplica os teus commits por cima, sem criar merge commits. Mantém o histórico limpo e linear. Podes tornar este comportamento o padrão com a configuração pull.rebase true.

git fetch
git fetch origin
git fetch --all --prune

Descarrega as novidades do remoto (novos commits, branches) sem alterar o teu trabalho local — podes inspecionar antes de decidir. O --prune apaga as referências locais a branches remotas que já foram apagadas no servidor.

git push origin nome-da-branch
git push

Envia os commits da tua branch local para o remoto origin. Se a branch não existir no remoto, é criada. Depois de definir o upstream (ver card seguinte), basta git push.

git stash
git stash push

Guarda as alterações não commitadas e devolve o working directory ao estado limpo do último commit. Perfeito quando precisas de mudar de branch "agora já" sem perder o trabalho em curso.

git stash apply
git stash apply stash@{2}

O git stash apply reaplica as alterações guardadas ao working directory sem remover o stash da lista — podes aplicá-lo em várias branches ou manter a cópia de segurança.

git stash push -m "WIP: formulário de login"

A flag -m dá uma mensagem ao stash — essencial para o identificar na lista quando tens vários guardados. Sem ela, o Git usa a mensagem genérica WIP on branch..., difícil de distinguir.

git stash pop

Aplica o stash mais recente e remove-o da lista, num só passo. É o fluxo normal: guardaste com git stash, voltas ao trabalho com git stash pop.

git stash -u
git stash --include-untracked

Por omissão, o stash ignora ficheiros novos (não rastreados). O -u inclui-os — útil quando criaste ficheiros que ainda não tinham levado git add.

git stash drop stash@{0}

Apaga um stash da lista sem o aplicar. Usa o identificador que vês em git stash list — por exemplo stash@{1} para o segundo mais recente.

git stash list
git stash show stash@{1}
git stash show -p stash@{1}

Lista todos os stashes com identificadores stash@{0}, stash@{1}, etc. (o {0} é o mais recente). O show resume as alterações e o -p mostra o diff completo — para veres o que guardaste antes de aplicar.

git stash clear

Apaga todos os stashes de uma vez. Atenção: não há confirmação nem reflog que os devolva facilmente — confirma com git stash list antes.

git commit --amend -m "Nova mensagem"
git add ficheiro-esquecido.php
git commit --amend --no-edit

Reescreve o último commit: altera a mensagem ou acrescenta ficheiros esquecidos (com --no-edit mantém a mensagem). Só em commits locais — fazer amend a um commit já enviado reescreve o histórico e causa confusão no remoto.

git restore ficheiro.php
git restore .

Reverte o ficheiro para o estado do último commit, descartando as alterações não guardadas. É o substituto moderno do antigo git checkout -- ficheiro. Atenção: alterações descartadas não são recuperáveis.

git reset HEAD~1
git reset HEAD~3

Desfaz o último commit mas mantém as alterações no working directory (modo mixed, o padrão). O número depois do ~ indica quantos commits recuar: HEAD~3 remove os três últimos.

git revert a1b2c3d
git revert HEAD

Cria um novo commit que anula as alterações do commit indicado, sem tocar no histórico. É a única forma segura de desfazer em branches partilhadas — ao contrário do reset, que reescreve o passado.

git reset --soft HEAD~1
git reset --mixed HEAD~1
git reset --hard HEAD~1

--soft: remove o commit, mantém tudo em staging. --mixed (padrão): remove o commit e o staging, mantém os ficheiros. --hard: apaga tudo — commit, staging e alterações no disco. O --hard é destrutivo: usa só com certezas.

git clean -n
git clean -f
git clean -fd
git clean -fdx

Apaga ficheiros não rastreados do working directory. O -n é um ensaio (mostra o que seria apagado, sem apagar); o -f força, o -d inclui pastas e o -x também os ignorados pelo .gitignore. Faz sempre -n primeiro.

git restore --staged ficheiro.php
git restore --staged .

Desfaz o git add: o ficheiro sai da staging area mas as alterações continuam no disco. Permite corrigir o que vai entrar no próximo commit sem perder trabalho.

git reset: move o ponteiro HEAD para trás — reescreve o histórico, só para commits locais. git revert: cria um commit que anula outro — seguro no remoto. git restore: desfaz alterações em ficheiros (no disco ou no staging), sem tocar em commits. Regra simples: local → reset; partilhado → revert; ficheiros → restore.

git rebase -i HEAD~3
git rebase --continue

Abre um editor com os últimos 3 commits para os reescreveres: mudar a ordem, juntar (squash), renomear (reword) ou apagar (drop). Depois de guardar, continua com git rebase --continue. Ideal para limpar commits "wip" antes de um push.

# .git/hooks/pre-commit
#!/bin/sh
php artisan test

Os hooks são scripts executados automaticamente em pontos-chave: pre-commit (antes de cada commit — ideal para correr testes ou linters), commit-msg (validar a mensagem), pre-push, etc. Vivem na pasta .git/hooks/ e não são versionados por omissão.

git gc
git prune
git count-objects -v

O git gc (garbage collection) comprime o histórico e remove objetos inacessíveis, mantendo a pasta .git pequena e rápida. O Git já o corre automaticamente de vez em quando; força-o em repositórios muito antigos ou após grandes limpezas.

No editor do rebase -i, cada linha começa por um comando:

• pick: mantém o commit como está.
• reword: mantém mas edita a mensagem.
• squash: junta ao commit anterior (mantendo as mensagens para editar).
• fixup: junta ao anterior, descartando a mensagem.
• drop: apaga o commit.
• edit: pára nesse commit para o alterares (com --amend).

git archive -o release-v1.0.zip v1.0.0
git archive --format=tar.gz --prefix=app/ HEAD > app.tar.gz

Exporta o estado do projeto num dado ponto (tag, branch ou commit) para um zip ou tar — sem o histórico .git. Ideal para entregar releases ou fazer backups do código.

git tag v1.0.0
git tag -a v1.0.0 -m "Versão 1.0.0"
git tag -l "v1.*"
git push origin v1.0.0
git push origin --tags

As tags marcam pontos fixos do histórico, normalmente versões (v1.0.0). As anotadas (-a) guardam autor, data e mensagem. As tags não vão para o remoto automaticamente — usa git push origin --tags.

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.lg "log --oneline --graph --all"

Os aliases criam atalhos para os comandos que mais usas. Depois de alias.st status, basta escrever git st. O clássico git lg dá-te o histórico visual completo com três teclas.

git worktree add ../projeto-hotfix hotfix/urgente
git worktree list
git worktree remove ../projeto-hotfix

O worktree cria uma segunda pasta de trabalho do mesmo repositório, noutra branch — sem clones duplicados. Perfeito para corrigir um bug urgente sem guardar o que tens em mãos com stash.

git submodule add https://github.com/lib/dependencia.git libs/dep
git submodule update --init --recursive
git clone --recurse-submodules URL

Os submodules embutem outro repositório dentro do teu, com a versão fixada num commit específico. Depois de clonar um projeto com submodules, o --init --recursive descarrega-os. Alternativas modernas: pacotes via composer ou npm.

Quando o Git abre o vim (num commit sem -m, por exemplo), estás em modo normal — as teclas não escrevem. Para editar, pressiona:

• i → inserir onde o cursor está
• a → inserir a seguir ao cursor
• o → criar uma linha nova por baixo

Vais ver -- INSERT -- no rodapé. Para voltar ao modo normal, pressiona Esc.

⚡ PERF – Melhorias de performance. Ex.: ⚡ PERF: otimizar query da base de dados.

🔒 SECURITY – Correção de vulnerabilidades. Ex.: 🔒 SECURITY: prevenir SQL Injection no login.

🚑 HOTFIX – Correção urgente em produção. Ex.: 🚑 HOTFIX: resolver downtime nos pagamentos.

🗑 REMOVE – Remover código ou ficheiros obsoletos. Ex.: 🗑 REMOVE: eliminar testes antigos.

No modo normal (depois de Esc):

• :w — guardar (write)
• :q — sair (quit)
• :wq — guardar e sair
• :q! — sair sem guardar
• :x — guardar e sair, mas só se houve alterações

Se ficaste preso no editor durante um commit: Esc, depois :wq e Enter.

Uma boa mensagem de git commit tem três partes:

• Título (até 50 caracteres): imperativo e direto — "Adicionar validação de email", não "adicionei".
• Linha em branco a separar.
• Corpo (opcional): explica o porquê e o contexto, não o como (o código mostra isso).

Se o título precisar de "e", provavelmente são dois commits.

📦 NEW – Adicionar nova funcionalidade ou módulo. Ex.: 📦 NEW: criar módulo de autenticação com Google.

➕ ADD – Adicionar código simples a algo já existente. Ex.: ➕ ADD: adicionar campo "telefone" no registo.

🐛 FIX – Corrigir um erro ou comportamento inesperado. Ex.: 🐛 FIX: corrigir falha na validação do email.

👌 IMPROVE – Melhorar código existente (performance, legibilidade). Ex.: 👌 IMPROVE: otimizar o carregamento do dashboard.

🚀 RELEASE – Publicar uma nova versão. Ex.: 🚀 RELEASE: versão 1.2.0 lançada.

git status
git add .
git commit -m "📦 NEW: adicionar paginação"
git pull --rebase
git push

O ciclo seguro do dia a dia: verifica o estado com git status, prepara com git add, guarda com git commit, sincroniza com git pull --rebase (resolve conflitos localmente) e só então envia com git push.

📝 DOCS – Atualizações de documentação. Ex.: 📝 DOCS: atualizar README com instruções de instalação.

🖌 STYLE – Alterações de estilo/formatação (sem afetar lógica). Ex.: 🖌 STYLE: ajustar cores e posição dos botões.

🐳 DOCKER – Alterações em configurações ou imagens Docker. Ex.: 🐳 DOCKER: atualizar imagem base do container.

♻ REFACTOR – Refatoração sem mudar comportamento. Ex.: ♻ REFACTOR: dividir função grande em métodos menores.

✅ TEST – Adicionar ou melhorar testes automatizados. Ex.: ✅ TEST: testes unitários para autenticação.

Nomes consistentes mantêm o repositório previsível:

• feature/nome — funcionalidade nova (nasce de main/develop).
• bugfix/nome — bug do dia a dia, não crítico.
• hotfix/nome — urgência em produção.
• release/1.2.0 — preparação de versão (changelog, testes finais).

Usa minúsculas e hífenes (feature/login-social) e sê específico: fix-bug não diz nada a ninguém.