Git, branches e pull requests

Identificação

• Duração: 2 horas
• Tipo: teoria aplicada e laboratório
• Entrega: fluxo de colaboração versionado
• Laboratório: ../exemplos/aula-3.5/index.html

Introdução

O que é Git?

Git é um sistema de controle de versão distribuído. Ele registra versões dos arquivos, permite comparar mudanças, criar linhas paralelas de trabalho e recuperar estados anteriores.

Git não é uma linguagem de programação e não é um serviço de armazenamento em nuvem. É um programa que pode ser instalado e executado no computador.

Todo Git é GitHub?

Não. Git é a tecnologia de versionamento. GitHub é uma plataforma que hospeda repositórios Git e acrescenta recursos como pull requests, issues, revisão, permissões e automações.

Outras plataformas incluem GitLab, Bitbucket e servidores próprios. Também é possível usar Git sem nenhuma delas.

Consigo ter Git local?

Sim. Este fluxo funciona sem internet:

git init
git add .
git commit -m "Cria estrutura inicial"

Os commits ficam na pasta oculta .git do próprio projeto. Um remoto só é necessário para compartilhar, manter outra cópia ou colaborar pela rede.

Git é um backup?

Ele ajuda a recuperar versões, mas um repositório somente no mesmo disco não é um backup suficiente. Se o disco falhar, arquivos e histórico podem ser perdidos. Mantenha cópias remotas e uma estratégia de backup adequada.

O que é uma branch?

Branch é um nome móvel que aponta para uma sequência de commits. Ela permite desenvolver uma mudança sem alterar imediatamente a linha principal.

git switch -c feature/filtro-tarefas

Criar uma branch é uma operação local. Publicá-la é outra ação:

git push -u origin feature/filtro-tarefas

O que é pull request?

Pull request, ou PR, é uma proposta feita em uma plataforma como GitHub para integrar uma branch em outra. Ele oferece conversa, revisão e verificações.

Não existe um comando Git universal chamado git pull-request. O PR pertence à plataforma. No GitLab, o recurso equivalente é chamado merge requisição.

git pull é a mesma coisa que pull request?

Não:

• git pull: comando Git que busca e integra mudanças de um remoto;
• pull request: página de revisão e proposta de integração em uma plataforma.

Onde isso entra no projeto?

Criaremos uma branch para uma funcionalidade do painel TypeScript, produziremos commits pequenos, executaremos a porta de qualidade da aula anterior e simularemos uma revisão antes da integração.

Objetivos

Ao final da aula, o aluno deverá conseguir:

1. diferenciar Git e GitHub;
2. criar e usar um repositório local;
3. explicar working tree, staging area e commit;
4. inspecionar mudanças antes de registrá-las;
5. criar branches;
6. realizar commits claros e pequenos;
7. diferenciar repositório local e remoto;
8. usar fetch, pull e push conscientemente;
9. explicar pull requests;
10. identificar e resolver conflitos simples;
11. executar uma revisão antes do merge;
12. evitar o versionamento de segredos.

Pré-requisitos

• terminal e sistema de arquivos;
• Aula 3.4 concluída;
• projeto TypeScript com comandos de qualidade.

Pergunta orientadora

Como registrar, compartilhar e revisar mudanças sem perder a história nem misturar trabalhos incompletos?

Roteiro sugerido

1. Instalação e identificação

Verifique:

git --version

Configure a autoria dos commits:

git config --global user.name "Seu Nome"
git config --global user.email "voce@exemplo.com"

Esses dados identificam autoria; não autenticam automaticamente no GitHub.

2. Configuração global e local

Configuração global vale para o usuário. Configuração local, armazenada em .git/config, vale somente para o repositório e pode sobrescrever a global:

git config user.email "email-do-projeto@exemplo.com"

Para descobrir a origem de cada valor:

git config --list --show-origin

3. Criando um repositório local

Dentro da pasta do projeto:

git init

Isso cria .git, onde ficam objetos, referências e configurações. Não execute git init em pastas amplas com arquivos pessoais.

4. Clonar ou inicializar?

• git init: começa um histórico em uma pasta;
• git clone URL: cria uma cópia local de um repositório existente e normalmente configura um remoto.

Clonar não significa editar diretamente o servidor. O trabalho continua local até um push.

5. Os três espaços principais

Working tree → Staging area → Repositório local
    git add          git commit

• working tree: arquivos que você edita;
• staging area: seleção preparada para o próximo commit;
• repositório local: histórico confirmado dentro de .git.

O remoto é uma quarta localização, sincronizada separadamente.

6. git status

git status

Ele mostra branch atual, arquivos modificados, preparados e não rastreados. Use antes e depois de operações importantes.

7. Arquivos rastreados e não rastreados

Um arquivo novo começa como untracked. Depois de ser incluído em um commit, passa a ser rastreado. Modificações posteriores aparecem no status.

Git não acompanha pastas vazias; acompanha conteúdo de arquivos.

8. Inspecionando diferenças

Mudanças ainda não preparadas:

git diff

Mudanças no staging:

git diff --staged

Revise o diff para evitar arquivos acidentais, registros, credenciais ou código de depuração.

9. Staging area

Prepare um arquivo específico:

git add src/task-service.ts

Preparar tudo com git add . é conveniente, mas exige revisão. A staging area permite formar um commit coerente mesmo quando a pasta contém outras alterações.

10. Retirando do staging

git restore --staged src/task-service.ts

Isso remove o arquivo da seleção do próximo commit sem apagar a alteração da working tree.

11. Commit

git commit -m "Adiciona filtro de tarefas por status"

Um commit é um registro do estado preparado, com autor, data, mensagem e ligação ao commit anterior. Ele não envia nada à internet.

12. Mensagens úteis

Prefira mensagens que descrevam intenção:

Adiciona validação do status da tarefa
Corrige total exibido no resumo
Documenta execução dos testes

Evite alterações, teste, coisas ou uma sequência de final-agora-vai.

13. Commits pequenos e coerentes

Um bom commit:

• possui uma finalidade;
• mantém o projeto em estado compreensível;
• não mistura refatoração e funcionalidade sem necessidade;
• pode ser revisado e revertido com menor risco.

Pequeno não significa uma linha; significa uma unidade lógica.

14. Histórico

git log --oneline --decorate --graph --all

O histórico ajuda a entender quando branches divergiram e onde referências apontam.

15. O que é HEAD?

HEAD representa a posição atualmente selecionada, normalmente a branch ativa. Ao fazer commit, a branch e HEAD avançam para o novo commit.

Evite manipular .git manualmente; use comandos Git.

16. Criando uma branch

git switch -c feature/filtro-tarefas

O comando cria a branch a partir do commit atual e muda para ela. Nomes como feature/..., fix/... e docs/... comunicam propósito, mas a convenção deve ser definida pela equipe.

17. Alternando branches

git switch main
git switch feature/filtro-tarefas

Mudanças não confirmadas podem impedir ou acompanhar a troca. Consulte git status antes de mudar.

18. Branch não é uma cópia completa

Git armazena objetos e referências de maneira eficiente. Uma branch é, em essência, um apontador para um commit. Por isso criar branches costuma ser rápido.

19. .gitignore

Exemplo:

node_modules/
dist/
coverage/
.env

.gitignore não remove um arquivo que já foi rastreado. Além disso, ignorar .env não apaga um segredo que já entrou no histórico.

20. Segredos nunca devem ser commitados

Não versione:

• senhas;
• tokens;
• chaves privadas;
• credenciais do banco;
• arquivos reais de ambiente.

Use .env.example somente com nomes de variáveis e valores fictícios. Se um segredo for exposto, revogue-o; apagar o arquivo do último commit não basta.

21. Repositório remoto

Um remoto é um nome associado a uma URL:

git remote add origin https://servidor/equipe/projeto.git
git remote -v

origin é uma convenção, não uma palavra obrigatória. O remoto pode estar no GitHub, GitLab, rede interna ou até em outro caminho acessível.

22. Branch local e branch remota

main e origin/main não são o mesmo objeto:

• main: branch local que você move com commits;
• origin/main: referência local da última posição conhecida no remoto.

git fetch atualiza referências remotas sem integrar automaticamente na branch atual.

23. fetch, pull e push

git fetch origin
git pull --ff-only
git push

• fetch: baixa referências e objetos;
• pull: busca e integra na branch atual;
• push: envia referências e objetos locais ao remoto.

Prefira entender o que será integrado em vez de usar pull mecanicamente.

24. Publicando uma branch

git push -u origin feature/filtro-tarefas

-u configura a relação de acompanhamento. Depois, git push e git pull sabem qual branch remota usar, conforme configuração.

25. Autenticação

Um remoto HTTPS pode usar credencial gerenciada ou token. Um remoto SSH usa chaves. Isso autentica o acesso à plataforma; é diferente de user.name e user.email dos commits.

Nunca coloque token dentro da URL versionada ou de scripts do projeto.

26. Pull request

Após publicar a branch, a plataforma permite abrir uma proposta:

feature/filtro-tarefas → main

Um bom PR informa:

• problema e solução;
• alterações principais;
• como testar;
• evidências relevantes;
• riscos e pontos de atenção.

27. Revisão de código

O revisor verifica correção, clareza, segurança, testes e aderência ao escopo. A revisão deve discutir o código, não a pessoa.

Comentários úteis explicam impacto e sugerem uma ação verificável.

28. Verificações automáticas

O PR pode executar:

npm ci
npm run quality

Um fluxo aprovado é evidência importante, mas não substitui a revisão humana nem garante ausência de todos os defeitos.

29. Merge

Estratégias comuns:

• merge commit: preserva explicitamente a integração;
• squash: reúne os commits do PR em um commit;
• rebase merge: reaplica commits em uma linha linear.

A equipe deve escolher uma política consistente. Não existe uma estratégia melhor para todos os contextos.

30. Conflitos

Um conflito ocorre quando Git não consegue decidir sozinho como combinar mudanças. O arquivo pode conter marcadores:

<<<<<<< HEAD
versão atual
=======
outra versão
>>>>>>> feature

Leia as duas intenções, edite o resultado correto, remova os marcadores, execute os testes e então prepare a resolução.

31. Conflito não é erro da pessoa

Conflitos são consequência normal de trabalhos que tocaram regiões relacionadas. Resolva com contexto de negócio; escolher sempre “ours” ou “theirs” pode descartar uma mudança necessária.

32. Atualizando a branch

Antes do merge, a equipe pode integrar main na feature por merge ou rebase. Rebase reescreve commits; evite reescrever histórico compartilhado sem coordenação.

Nunca use push --force de forma automática. Se a política exigir atualização de uma branch própria, entenda o impacto e prefira proteções como --force-with-lease.

33. Desfazendo com segurança

Para desfazer um commit já compartilhado:

git revert IDENTIFICADOR

Isso cria um novo commit inverso e preserva o histórico. Comandos que reescrevem ou apagam trabalho exigem mais cuidado.

34. Laboratório guiado

Abra o simulador de fluxo Git.

Etapa 1 — Trabalhe localmente

Edite o arquivo, prepare a mudança e crie um commit. Observe que nenhuma dessas ações exige GitHub ou internet.

Etapa 2 — Crie uma branch

Abra a branch de funcionalidade antes de editar. Veja os apontadores locais mudarem.

Etapa 3 — Configure o remoto

Conecte um remoto simulado e publique a branch. Só aqui a mudança sai do repositório local.

Etapa 4 — Abra e revise o PR

O pull request só fica disponível depois que a branch existe no remoto. Execute a qualidade e aprove a revisão antes do merge.

35. Fluxo recomendado da aula

atualizar main
→ criar branch
→ editar
→ revisar diff
→ preparar
→ executar qualidade
→ commit
→ publicar branch
→ abrir PR
→ revisar
→ integrar

36. Erros comuns

Achar que commit envia ao GitHub

Commit é local. push sincroniza com o remoto.

Trabalhar sempre na main

Isso mistura trabalho incompleto com a linha de integração.

Versionar node_modules

O projeto deve registrar manifesto e lockfile, não a pasta instalada.

Commitar segredos

Mesmo removidos depois, eles podem permanecer no histórico.

Fazer um commit com assuntos diferentes

Revisão e reversão ficam mais difíceis.

Resolver conflito sem testar

Um arquivo sem marcadores ainda pode estar logicamente incorreto.

37. Boas práticas

• execute git status frequentemente;
• examine git diff antes de preparar;
• examine git diff --staged antes de confirmar;
• crie branches com propósito claro;
• produza commits coerentes;
• não versione segredos ou dependências instaladas;
• sincronize conscientemente;
• descreva como testar o PR;
• mantenha verificações aprovadas;
• trate revisão como colaboração técnica.

38. Exercícios

Exercício 1 — Conceitos

Classifique operações como local, remota ou pertencente à plataforma.

Exercício 2 — Primeiro histórico

Crie um repositório local com três commits pequenos e inspecione o registro.

Exercício 3 — Staging seletivo

Altere dois arquivos e inclua apenas um no próximo commit.

Exercício 4 — Branch

Crie feature/resumo-tarefas, confirme uma mudança e retorne à main.

Exercício 5 — Revisão

Escreva título, descrição e roteiro de testes para um PR simulado.

39. Desafio

Entregue um fluxo completo que contenha:

• repositório local;
• .gitignore seguro;
• branch de funcionalidade;
• pelo menos dois commits coerentes;
• fluxo de qualidade aprovado;
• branch publicada;
• descrição de pull request;
• revisão simulada;
• registro da estratégia de merge escolhida.

40. Lista de verificação de conclusão

• Sei diferenciar Git e GitHub.
• Consigo usar Git somente local.
• Entendo working tree, staging e commit.
• Reviso diff antes do commit.
• Crio e alterno branches.
• Diferencio branch local e remota.
• Diferencio fetch, pull e push.
• Sei explicar pull request.
• Entendo como resolver um conflito simples.
• Nunca versiono segredos.

41. Critérios de avaliação

Resumo

Nesta aula, aprendemos que:

• Git é independente de GitHub;
• repositórios e commits podem ser totalmente locais;
• staging seleciona o próximo commit;
• branches são apontadores para commits;
• remotos são cópias sincronizadas separadamente;
• git pull não é pull request;
• pull request pertence à plataforma de colaboração;
• revisão, qualidade e merge completam o fluxo;
• segredos não devem entrar no histórico.

Próxima aula

Na Aula 3.6, reuniremos testes, documentação e todo o projeto TypeScript em uma entrega final reproduzível.