Aprende a usar o Git e o GitHub para gerir o teu código, colaborar em equipa e contribuir para projectos open source — do zero ao avançado.
Conceitos fundamentais antes de começar
Sistema de controlo de versões distribuído criado por Linus Torvalds em 2005. Regista todas as alterações ao código ao longo do tempo, permitindo voltar a qualquer ponto anterior.
Ferramenta local · CLIPlataforma online que aloja repositórios Git. Adiciona ferramentas de colaboração — Pull Requests, Issues, Actions, Pages, etc. É onde vive a maioria dos projectos open source do mundo.
Plataforma cloud · github.comUm repositório (ou "repo") é a pasta do projecto rastreada pelo Git. Contém todos os ficheiros, histórico de commits e branches. Pode ser local (no teu computador) ou remoto (no GitHub).
Local · RemoteUm commit é uma fotografia do estado dos ficheiros num determinado momento. Cada commit tem uma mensagem descritiva e um identificador único (hash SHA). É a unidade básica do histórico Git.
Snapshot · Hash SHAUma linha de desenvolvimento paralela. A branch principal chama-se main (ou master). Cria branches para desenvolver funcionalidades sem afectar o código estável.
main · feature · hotfixFundir os commits de uma branch noutra chama-se merge. No GitHub, este processo passa por um Pull Request — uma proposta de alteração que pode ser revista e aprovada pela equipa.
PR · Code ReviewInstalar, configurar e criar o teu primeiro repositório
brew install git. Em Linux usa apt install git ou o gestor de pacotes da tua distribuição. Recomenda-se também instalar o GitHub Desktop (interface gráfica) ou a extensão GitLens no VS Code.
Referência completa dos comandos mais utilizados
| Comando | O que faz |
|---|---|
| 📋 Estado e Informação | |
| git status | Mostra o estado actual do repositório — ficheiros modificados, staged e untracked. |
| git log | Lista o histórico de commits. Usa --oneline --graph para uma vista compacta em árvore. |
| git diff | Mostra as alterações ainda não adicionadas à staging area. Com --staged mostra o que está pronto para commit. |
| git show <hash> | Detalha um commit específico — alterações, autor, data e mensagem. |
| ➕ Staging e Commits | |
| git add <ficheiro> | Adiciona um ficheiro à staging area (prepara para commit). |
| git add . | Adiciona todos os ficheiros alterados e novos à staging area. |
| git commit -m "msg" | Cria um commit com a mensagem indicada. A mensagem deve ser clara e no imperativo. |
| git commit --amend | Altera o último commit — útil para corrigir a mensagem ou adicionar ficheiros esquecidos. |
| 🌐 Remoto (GitHub) | |
| git remote -v | Lista os repositórios remotos configurados e os seus URLs. |
| git remote add origin <url> | Liga o repositório local a um repositório remoto (normalmente chamado origin). |
| git push origin main | Envia os commits locais para a branch main do repositório remoto. |
| git pull origin main | Descarrega e integra as alterações do remoto na branch actual. |
| git fetch | Descarrega as alterações do remoto mas não as integra — permite inspeccionar antes de fazer merge. |
| ↩️ Desfazer Alterações | |
| git restore <ficheiro> | Descarta as alterações de um ficheiro (não staged), voltando ao último commit. |
| git restore --staged <ficheiro> | Remove um ficheiro da staging area sem perder as alterações. |
| git revert <hash> | Cria um novo commit que desfaz as alterações de um commit anterior — seguro para histórico partilhado. |
| git reset --hard HEAD~1 | Apaga o último commit e todas as suas alterações. Usar com cuidado — é destrutivo! |
Como trabalhar com ramos de desenvolvimento de forma eficaz
| Comando | O que faz |
|---|---|
| git branch | Lista todas as branches locais. A branch activa tem um asterisco (*) à frente. |
| git branch -a | Lista branches locais e remotas. |
| git branch <nome> | Cria uma nova branch a partir da branch actual (sem trocar para ela). |
| git switch <nome> | Troca para a branch indicada. Substituto moderno de git checkout. |
| git switch -c <nome> | Cria e troca imediatamente para a nova branch — equivale a branch + switch. |
| git merge <branch> | Funde a branch indicada na branch actual. Cria um merge commit se houver divergência. |
| git rebase <branch> | Reescreve o histórico aplicando os commits por cima da branch indicada — histórico mais limpo. |
| git branch -d <nome> | Apaga uma branch local que já foi fundida. Usa -D para forçar. |
| git push origin --delete <nome> | Apaga uma branch no repositório remoto. |
Do início de uma tarefa ao código em produção
Obter a versão mais recente do código
Criar uma branch para a tarefa
Desenvolver e testar localmente
Guardar alterações com mensagem clara
Enviar para o GitHub
Propor, rever e fundir o código
Antes de começar qualquer trabalho, garante que tens o código mais recente. Nunca desenvolvas na branch main directamente.
git switch main · git pull origin mainO nome da branch deve descrever a tarefa: feature/nome-funcionalidade, fix/nome-bug, docs/atualizar-readme. Segue as convenções da tua equipa.
git switch -c feature/nome-da-tarefaFaz commits pequenos e frequentes, cada um com uma única responsabilidade. Usa prefixos convencionais: feat:, fix:, docs:, style:, refactor:, test:.
git add . · git commit -m "feat: descrição clara"Na primeira vez usa -u para ligar a branch local à remota — nas vezes seguintes basta git push.
git push -u origin feature/nome-da-tarefaNo GitHub, clica em "Compare & pull request". Escreve uma descrição clara do que foi feito e porquê. Solicita revisão a colegas. O PR permite discussão de código, sugestões e aprovação antes do merge.
GitHub → Pull Requests → New Pull RequestApós aprovação, faz o merge do PR no GitHub (Squash, Merge Commit ou Rebase). Apaga a branch remota. Localmente, volta à main, faz pull e apaga a branch local.
git switch main · git pull · git branch -d feature/…git push --force numa branch partilhada — isso reescreve o histórico dos outros. Nunca commites credenciais, passwords ou ficheiros .env — usa sempre um .gitignore apropriado.
As principais secções e o que encontras em cada uma
Navegação no código fonte, visualização de ficheiros, histórico de commits por ficheiro e download do repositório.
Sistema de rastreio de bugs, tarefas e pedidos de funcionalidades. Suporta labels, milestones, assignees e templates.
Lista e gestão de PRs abertos, em revisão e fechados. Inclui diff de código, comentários inline e histórico de revisões.
CI/CD integrado — automatiza testes, builds e deployments com workflows YAML. Executa a cada push ou PR.
Quadros Kanban e tabelas para gestão ágil de tarefas, ligados a Issues e Pull Requests do repositório.
Documentação extensa do projecto em Markdown. Ideal para guias de instalação, arquitectura e decisões de design.
Configurações do repo: colaboradores, branch protection rules, webhooks, secrets e visibilidade público/privado.
Cria um repositório com o mesmo nome do teu username — o README.md aparece na tua página de perfil GitHub.
Contribuir para projectos de outros e trabalhar em equipa
Cria uma cópia de um repositório na tua conta GitHub. Usada para contribuir para projectos onde não tens acesso de escrita — fazes alterações no teu fork e propões via Pull Request.
GitHub → ForkManter o teu fork actualizado com o repositório original. Configura o upstream remoto e faz git pull upstream main regularmente para não ficares desactualizado.
git remote add upstream <url>Usa labels como bug, enhancement, good first issue para organizar. good first issue é especialmente importante para atrair novos contribuidores open source.
Issues → LabelsNo Pull Request, podes comentar linha a linha, sugerir alterações directamente (Suggest changes), aprovar ou solicitar modificações. É a base da qualidade em equipa.
PR → Review changesFicheiro que descreve como contribuir para o projecto — guias de estilo, processo de PR, como reportar bugs e como executar os testes localmente.
Boa práticaAutomatiza tarefas com workflows YAML: executa testes a cada PR, faz build automático, deploy para produção após merge. Define-se em .github/workflows/.
Actions → WorkflowsTruques que tornam o fluxo de trabalho muito mais rápido