UC00617

Utilizar serviços Git e GitHub

Controlo de versões, branches, tags, conflitos e colaboração

Curso profissional · 25h · Desenvolvimento de software

Plano

  1. Controlo de versões
  2. Instalar e configurar o Git
  3. Repositórios locais e commits
  4. Desfazer e editar o historial
  5. Tags
  6. Branches e merge
  7. Resolução de conflitos
  8. Cliente gráfico
  9. GitHub: conta, perfil e repositórios
  10. Repositórios remotos
  11. Colaborar e contribuir
  12. Workflow profissional e normas

Bloco 1 · Controlo de versões e instalação

O problema das cópias com nomes

index.html
index_v2.html
index_v3_FINAL.html
index_FINAL_mesmo.html
index_usar_este.html
  • Qual é a versão atual?
  • O que mudou entre versões?
  • Como se juntam duas pessoas no mesmo ficheiro?
  • Como se volta atrás?

Três modelos de controlo de versões

Modelo Exemplos Limitação
Local RCS Não serve para equipas
Centralizado CVS, Subversion Sem servidor, limitado
Distribuído Git, Mercurial Exige perceber local e remoto

No modelo distribuído, cada pessoa tem o historial completo.

Porquê o Git

  • Criado por Linus Torvalds em 2005.
  • Distribuído: trabalho offline.
  • Rápido: operações locais.
  • Branches baratos.
  • Integridade: cada commit tem um hash.
  • Gratuito e de código aberto (git-scm.com).

Terminologia essencial

Termo Significado
Repositório Pasta acompanhada pelo Git (.git)
Commit Instantâneo com mensagem
Branch Linha de trabalho com nome
HEAD Onde estás agora
Remote / origin Repositório noutro sítio
Clone, push, pull, fetch Copiar, enviar, receber

Instalar o Git

Sistema Como
Windows Git for Windows (git-scm.com)
macOS brew install git
Debian e Ubuntu sudo apt install git
Fedora sudo dnf install git 
git --version

Configuração inicial

git config --global user.name "Joana Ferreira"
git config --global user.email "joana@exemplo.pt"
git config --global init.defaultBranch main
git config --global pull.rebase false
git config --list --show-origin

Três níveis: sistema, utilizador (--global), repositório.

Bloco 2 · Repositório local

Criar ou clonar

mkdir meu-projeto
cd meu-projeto
git init

git clone https://github.com/utilizador/repositorio.git

A pasta .git guarda todo o historial.

As três áreas do Git

Diretório de trabalho -> Área de preparação -> Repositório
        git add          git commit
Área Conteúdo
Trabalho Ficheiros como estão
Preparação O que entra no próximo commit
Repositório Commits gravados

Estados dos ficheiros

Estado Significado
Untracked Novo, o Git não o conhece
Modified Alterado desde o último commit
Staged Preparado para o commit
Committed Gravado no historial 
git status

Preparar e gravar

git add index.html
git add .
git commit -m "Adiciona página inicial"
git commit -am "Corrige título"

O -a só apanha ficheiros já acompanhados.

Consultar o historial

git log --oneline --graph --all
git log -p
git log --author="Joana"
git log --grep="menu"
git show abc1234
git blame index.html

O ficheiro .gitignore

node_modules/
dist/
*.log
.env
*.pem
.DS_Store
  • Cria-o no primeiro commit.
  • Só afeta ficheiros ainda não acompanhados.
  • Modelos: github.com/github/gitignore

Exemplo resolvido · primeiro repositório

  1. git init
  2. Criar index.html e style.css
  3. git add index.html style.css
  4. git commit -m "Cria estrutura inicial do site"
  5. Editar o CSS e git commit -am "Define cor de fundo"
  6. git log --oneline mostra 2 commits

Desfazer antes do commit

git restore index.html
git restore --staged index.html
git commit --amend -m "Mensagem corrigida"
  • restore sem --staged perde as alterações.
  • --amend só em commits não enviados.

Reset e revert

Comando Efeito Em commits publicados
reset --soft HEAD~1 Desfaz, mantém preparado Não
reset HEAD~1 Desfaz, mantém no trabalho Não
reset --hard HEAD~1 Desfaz e apaga Não
revert abc1234 Commit novo que anula Sim

Editar o historial

git rebase -i HEAD~3
Palavra Efeito
pick Manter
reword Mudar a mensagem
squash Fundir, juntando mensagens
fixup Fundir, sem a mensagem
drop Eliminar

Stash, cherry-pick e reflog

git stash          # guardar a meio
git stash pop      # voltar a aplicar
git cherry-pick abc1234
git reflog
git reset --hard HEAD@{1}

O reflog só salva o que chegou a ser gravado.

Tags

Tipo Comando
Leve git tag v1.0.0
Anotada git tag -a v1.0.0 -m "Primeira versão estável" 
git push origin v1.0.0
git push origin --tags

O git push normal não envia tags.

Bloco 3 · Branches e conflitos

O que é uma branch

main:         A---B---C---------M
                       \       /
feature/menu:           D---E---
  • Um ponteiro com nome, para um commit.
  • Criar é instantâneo.
  • Experimenta-se sem mexer em main.

Operações com branches

git branch
git switch -c feature/menu
git switch main
git branch -m novo-nome
git branch -d feature/menu
git branch -D feature/menu

switch existe desde a versão 2.23; checkout -b é o equivalente antigo.

Merge: fast-forward e três vias

Fast-forward:  main  A---B---C---D---E

Três vias:     main  A---B---C---D---M
                          \         /
                           E---F---

git merge --no-ff força o commit de merge.

Merge ou rebase

Merge Rebase
Historial Fiel, com merges Linear
Reescreve commits Não Sim
Em branches partilhadas Seguro Não

Regra de ouro: nunca faças rebase de commits já enviados.

Estratégias de branching

Estratégia Branches Uso
Git Flow main, develop, feature, release, hotfix Versões em datas fixas
GitHub Flow main e branches curtas Equipas pequenas, a deste curso
Trunk-based quase só main Equipas maduras

Nomes: feature/, fix/, docs/, chore/

Conflitos: quando acontecem

  • Mesma zona do mesmo ficheiro, alterações diferentes.
  • Ou um apaga um ficheiro que o outro alterou.
  • O Git não decide por ti.
CONFLICT (content): Merge conflict in index.html

Anatomia de um conflito

<<<<<<< HEAD
<h1>Bem-vindo ao meu site</h1>
=======
<h1>O meu portefólio</h1>
>>>>>>> feature/titulo
Marcador Significado
<<<<<<< HEAD Versão da branch atual
======= Separador
>>>>>>> feature/titulo Versão a fundir

Resolver localmente

  1. git status
  2. Decidir e editar o texto final
  3. Apagar os três marcadores
  4. git add ficheiro
  5. git commit
  6. Testar o projeto
git checkout --ours ficheiro
git checkout --theirs ficheiro
git merge --abort

No GitHub: Resolve conflicts, editar, Mark as resolved, Commit merge.

Cliente gráfico

Tarefa Terminal GitHub Desktop
Clonar git clone File, Clone repository
Gravar git add + git commit Changes, Commit
Branch git switch -c Current Branch, New
Enviar git push Push origin
Receber git pull Pull origin

Outros: VS Code, GitKraken, Sourcetree.

Bloco 4 · GitHub

O que é o GitHub

Funcionalidade Para que serve
Repositórios Alojar código
Pull requests Propor e rever
Issues Erros e tarefas
Actions Automatizar
Pages Sites estáticos
Releases Versões publicadas

O Git é o programa; o GitHub é um serviço. Alternativas: GitLab, Bitbucket, Codeberg.

Criar e proteger a conta

  1. github.com, Sign up
  2. Email, palavra-passe forte, utilizador sóbrio
  3. Confirmar o email
  4. Ativar a autenticação de dois fatores
  5. Guardar os códigos de recuperação

Por HTTPS usa-se token ou gestor de credenciais, não a palavra-passe da conta.

Perfil e página pessoal

  • Perfil: github.com/nome.
  • Repositório com o teu nome de utilizador + README.md = apresentação no perfil.
  • Repositório nome.github.io + index.html = página em https://nome.github.io.
  • Pages serve só conteúdo estático.

Criar um repositório

Campo Escolha
Nome loja-demo (minúsculas, hífen)
Description Uma frase
Visibilidade Público ou privado
README Sim
.gitignore Modelo da linguagem
Licença MIT é permissiva

O ficheiro README.md

# Loja Demo

Pequena loja online de exemplo.

## Instalação
## Utilização
## Licença

Responde a 4 perguntas: o que é, como se instala, como se usa, como contribuir.

Ligar o local ao remoto

git remote add origin https://github.com/nome/meu-site.git
git remote -v
git branch -M main
git push -u origin main

O -u liga main a origin/main: depois basta git push.

HTTPS ou SSH

HTTPS SSH
Autenticação Token ou gestor Par de chaves
Configuração Simples Gerar e registar chave
Dia a dia Pode pedir credenciais Sem pedidos 
ssh-keygen -t ed25519 -C "email"
ssh -T git@github.com

Copiar o ficheiro .pub; a chave privada nunca sai da máquina.

Push, fetch e pull

Comando Faz
git push Envia commits
git fetch Descarrega sem integrar
git pull fetch + merge
git pull --rebase fetch + rebase

Push recusado? Faz git pull, resolve e volta a enviar. Não forces.

Bloco 5 · Colaborar

Fork e upstream

  1. Fork na plataforma
  2. git clone do teu fork
  3. git remote add upstream <original>
  4. git fetch upstream e git merge upstream/main

origin = o teu fork · upstream = o original

Fluxo de um pull request

  1. Branch nova
  2. Commits
  3. git push -u origin feature/x
  4. Compare & pull request
  5. Revisão e discussão
  6. Novos commits atualizam o PR
  7. Merge pull request
  8. git switch main, git pull, git branch -d

Revisão de código

Revisor: ler tudo, comentar linhas, perguntar, sugerir, reconhecer o que está bem.

Autor: PR com cerca de 400 linhas no máximo, um propósito, relê o diff, responde a tudo.

Decisão: Comment, Approve, Request changes.

Bloco 6 · Workflow profissional e normas

Conventional Commits

<tipo>(<âmbito>): <resumo>
Tipo Uso
feat Funcionalidade
fix Correção
docs Documentação
refactor Reestruturação
test · chore · ci Testes, manutenção, integração

Resumo até 50 caracteres, a começar por um verbo, sem ponto final. Corpo até 72.

Segurança e dados pessoais

  • Nunca commitar palavras-passe, chaves, tokens, dados pessoais reais.
  • .env no .gitignore e .env.example sem valores.
  • RGPD: dados inventados para treinar.
  • Segredo publicado? Revoga primeiro, limpa depois.

Licenças e normas

  • Repositório público sem licença não autoriza reutilização.
  • MIT e Apache 2.0: permissivas. GPL: obras derivadas mantêm a licença.
  • Ao copiar código, respeitar a licença e indicar a origem.
  • Cumprir as regras internas da escola ou da empresa.

Erros comuns

Erro Solução
Identidade errada Configurar antes do 1.º commit
Trabalhar em main Branch por tarefa
reset --hard sem pensar Ler o status; usar o reflog
Rebase de commits enviados Merge em branches partilhadas
Marcadores esquecidos Procurar <<<<
Tags por enviar git push origin v1.0.0

Síntese

  • Três áreas: trabalho, preparação, repositório.
  • Histórico: log, diff, amend, revert, reflog.
  • Branches e merge; rebase só local.
  • Conflitos: decidir, apagar marcadores, add, commit.
  • GitHub: conta com 2FA, README, remoto, PR.
  • Normas: sem segredos nem dados pessoais; licença explícita.

Obrigado

Git e GitHub: pratica num repositório de treino.

NOTAS DO PROFESSOR - Pedir à turma que reconheça a situação: quase todos já tiveram uma pasta assim. - Listar as cinco perguntas sem resposta e dizer que o Git responde a todas. - Ligar ao capítulo 1 da sebenta, secção 1.1.

NOTAS DO PROFESSOR - Explicar que distribuído significa cópia completa, não cópia parcial. - Consequência prática: quase tudo é instantâneo e funciona sem rede. - Comparar com a rede de partilha de ficheiros que os formandos já conhecem.

NOTAS DO PROFESSOR - Dizer que o Git nasceu para o núcleo do Linux e hoje é o padrão da profissão. - Explicar o hash como impressão digital do conteúdo. - Referir que a competência serve em qualquer empresa e linguagem.

NOTAS DO PROFESSOR - Fixar a direção: push envia, pull recebe, fetch só descarrega. - Mostrar no quadro um desenho local e remoto com setas. - Dizer que o vocabulário é pré-requisito do resto da unidade.

NOTAS DO PROFESSOR - Cada formando instala e corre git --version; só avança quem vir uma versão. - Se o comando não for reconhecido, fechar e reabrir o terminal. - No Windows, recomendar deixar o Git no PATH e o nome main para a branch inicial.

NOTAS DO PROFESSOR - Explicar que nome e email ficam em todos os commits e no historial. - Recomendar o mesmo email da conta GitHub. - Mostrar que a configuração do repositório prevalece sobre a global. - Explicar que sem pull.rebase o git pull recusa juntar historiais divergentes.

NOTAS DO PROFESSOR - Avisar que apagar a pasta .git faz perder o historial, ficando só os ficheiros. - O clone já configura o remote origin. - Pedir que cada formando crie o repositório de treino para as aulas.

NOTAS DO PROFESSOR - Este é o slide mais importante do bloco; desenhar as três caixas no quadro. - Explicar que a preparação serve para escolher o que entra em cada commit. - Dar o exemplo de cinco ficheiros alterados, dois da mesma tarefa.

NOTAS DO PROFESSOR - Correr git status ao vivo depois de cada passo da demonstração. - Dizer que é o comando que mais evita enganos. - Pedir que prevejam o estado antes de o correr.

NOTAS DO PROFESSOR - Mostrar a diferença entre git add ficheiro e git add ponto. - Explicar o que o -a faz e o que não faz com ficheiros novos. - Insistir em mensagens que começam por um verbo e dizem o que o commit faz.

NOTAS DO PROFESSOR - Mostrar o desenho das branches com --graph. - Explicar que bastam os primeiros 7 caracteres do hash. - Usar git blame para mostrar quem alterou cada linha.

NOTAS DO PROFESSOR - Explicar que ignorar depois de gravar exige git rm --cached. - Ligar o .env à segurança, que voltamos a ver no bloco 6. - Mostrar um modelo do repositório github/gitignore.

NOTAS DO PROFESSOR - Fazer em simultâneo com a turma, passo a passo. - No fim confirmar que git status diz working tree clean. - Corresponde ao exemplo resolvido do capítulo 3 da sebenta.

NOTAS DO PROFESSOR - Dizer que git restore existe desde a versão 2.23 e que os materiais antigos usam checkout. - Avisar que o descarte do diretório de trabalho não tem recuperação. - Explicar que o amend substitui o commit por outro com novo hash.

NOTAS DO PROFESSOR - Regra de decisão: commit só local pode levar reset; commit enviado leva revert. - Explicar HEAD~1 como o commit anterior ao atual. - Mostrar que o revert acrescenta historial em vez de o reescrever.

NOTAS DO PROFESSOR - Demonstrar a limpeza de três commits num repositório de treino. - Recordar que só se aplica antes de partilhar a branch. - Mostrar que reordenar as linhas reordena os commits.

NOTAS DO PROFESSOR - Usar o stash quando é preciso mudar de branch com trabalho a meio. - Mostrar o reflog como rede de segurança local. - Explicar que os registos do reflog expiram, por isso agir depressa.

NOTAS DO PROFESSOR - Explicar que uma tag não anda, ao contrário de uma branch. - Recomendar tags anotadas para versões partilhadas. - Mostrar a transformação de uma tag em release no GitHub.

NOTAS DO PROFESSOR - Explicar que não se copiam ficheiros, só se cria um ponteiro. - Referir que master é o nome antigo da branch principal. - Pedir que descrevam o desenho por palavras suas.

NOTAS DO PROFESSOR - Distinguir -d, que só apaga se estiver integrada, de -D, que apaga sempre. - Avisar que mudar de branch com alterações colidentes é recusado. - Treinar os comandos no repositório de treino.

NOTAS DO PROFESSOR - Explicar que o fast-forward só avança o ponteiro. - Mostrar que o commit de merge tem dois pais. - Perguntar quando é que um merge dá fast-forward.

NOTAS DO PROFESSOR - Mostrar o desenho de E e F que passam a E linha e F linha. - Reforçar a regra de ouro com um exemplo de equipa. - Recordar que o rebase interativo segue a mesma regra.

NOTAS DO PROFESSOR - Explicar que o GitHub Flow é o que o mini-projeto usa. - Pedir três nomes de branch bons e três maus. - Referir que nomes vagos como teste ou branch1 dificultam a revisão.

NOTAS DO PROFESSOR - Dizer que alterações em zonas diferentes são juntadas sozinhas. - Mostrar o git status com both modified. - Normalizar o conflito: faz parte do trabalho em equipa.

NOTAS DO PROFESSOR - Ler os marcadores em voz alta com a turma. - Avisar que marcadores esquecidos estragam o ficheiro. - Mostrar como procurar a sequência de sete sinais menor para confirmar que não sobrou nenhuma.

NOTAS DO PROFESSOR - Fazer um conflito de propósito em pares e resolvê-lo. - Explicar ours e theirs com cuidado, pois confundem. - Mostrar o merge --abort como saída de emergência.

NOTAS DO PROFESSOR - Mostrar a mesma operação nos dois modos para provar a equivalência. - O terminal é mais completo; o cliente é mais rápido a ver diferenças. - Pedir que gravem apenas um dos dois ficheiros alterados no cliente.

NOTAS DO PROFESSOR - Separar Git de GitHub, confusão muito frequente. - Dizer que no GitLab o pull request se chama merge request. - Pedir exemplos de projetos conhecidos alojados na plataforma.

NOTAS DO PROFESSOR - Insistir que o nome de utilizador é público e vai aparecer em endereços. - Cada formando ativa o 2FA durante a aula. - Nunca ditar nem partilhar palavras-passe ou tokens em voz alta ou no quadro.

NOTAS DO PROFESSOR - Mostrar um perfil bem cuidado e um README de perfil. - Avisar que tudo o que é publicado fica visível a todos. - Pedir que cada formando prepare duas linhas de apresentação.

NOTAS DO PROFESSOR - Explicar a diferença prática entre público e privado. - Mostrar o ecrã New repository e os campos um a um. - Referir que, sem licença, ninguém fica autorizado a reutilizar o código, mesmo num repositório público.

NOTAS DO PROFESSOR - Mostrar os elementos de Markdown mais usados na sebenta, secção 9.6. - Avaliar um README real em grupo com estas quatro perguntas. - Mencionar LICENSE, CONTRIBUTING.md e CHANGELOG.md como ficheiros habituais.

NOTAS DO PROFESSOR - Insistir em criar o repositório remoto vazio. - Explicar o que faz o -u. - Verificar no GitHub que os commits aparecem.

NOTAS DO PROFESSOR - Fazer a configuração SSH em conjunto, passo a passo. - Repetir que só o ficheiro com .pub se partilha. - Mostrar o teste ssh -T e a mensagem de sucesso.

NOTAS DO PROFESSOR - Explicar a mensagem rejected, fetch first. - Reservar o push --force para branches pessoais. - Mostrar git log main..origin/main depois de um fetch.

NOTAS DO PROFESSOR - Distinguir projeto próprio, com branches, de projeto alheio, com fork. - Pedir que desenhem os dois remotes e as setas. - Mostrar git remote -v com origin e upstream.

NOTAS DO PROFESSOR - Percorrer os oito passos com uma demonstração completa. - Mostrar os separadores Conversation, Commits e Files changed. - Explicar que cada push atualiza o PR sozinho.

NOTAS DO PROFESSOR - Treinar a escrita de comentários construtivos com exemplos. - Distinguir o que bloqueia o merge de uma sugestão menor, o nit. - Lembrar que a crítica é ao código e não à pessoa.

NOTAS DO PROFESSOR - Pedir que reescrevam três mensagens más para o formato correto. - Escolher uma língua para o projeto e manter. - Mostrar um commit com corpo e rodapé.

NOTAS DO PROFESSOR - Explicar que o historial mantém o que já foi apagado do ficheiro. - Reforçar a ordem: revogar a chave antes de limpar o historial. - Usar só dados inventados em todos os exercícios e no mini-projeto.

NOTAS DO PROFESSOR - Usar choosealicense.com para comparar licenças em aula. - Distinguir licença permissiva de licença que obriga a manter a mesma licença. - Ligar ao referencial: normas e regulamentos aplicáveis.

NOTAS DO PROFESSOR - Pedir à turma que diga qual destes já cometeu. - Ligar cada erro ao capítulo correspondente da sebenta. - Reforçar que errar num repositório de treino não custa nada.

NOTAS DO PROFESSOR - Pedir a cada formando que explique um ponto por palavras suas. - Ligar a síntese às três realizações do referencial. - Anunciar as fichas e o mini-projeto como aplicação.