Módulo 02 — Ambiente, ferramentas e versionamento

1. O ambiente das duas stacks

A gente treina com duas stacks de back-end (Node.js + Express e PHP), as duas falando com MySQL, e um front único em HTML/CSS/JS. Na prova você usa a que estiver liberada e mais afiada. O ambiente precisa estar pronto e idêntico nas duas máquinas: mesma versão de tudo, mesmas extensões, mesmos atalhos. Máquinas diferentes geram o clássico "na minha funciona", que é tempo perdido.

1.1 O que instala e como conferir

Depois de instalar, configurar o Git uma vez (identidade que assina cada commit):

git config --global user.name "Seu Nome"
git config --global user.email "seu@email.com"
git config --global init.defaultBranch main

1.2 VS Code: extensões e configurações que pagam o tempo investido

Extensão é ferramenta, não enfeite. As que valem pra nossa realidade:

Duas configurações que mudam o jogo (Ctrl+, abre as configurações):

• Format On Save ligado: todo arquivo sai formatado sem você pensar nisso. Código formatado é um dos itens mais baratos de organização que a banca enxerga.
• Auto Save em onFocusChange: nunca mais "mas eu tinha certeza que salvei".

1.3 Atalhos: velocidade que vira escopo entregue

Boa parte da velocidade de dev é não usar o mouse pra tudo. Os que valem treinar até virarem automáticos:

1.4 O fluxo de montagem: subir um projeto do zero

Nos primeiros minutos da prova, quem tem o caminho de montagem decorado sai na frente. Não é decorar código, é decorar o fluxo. As duas sequências, lado a lado:

Node.js + Express:

mkdir wedding-pass && cd wedding-pass
git init
npm init -y
npm install express mysql2
npm install --save-dev nodemon
# cria app.js com o esqueleto do servidor
# cria .gitignore (seção 5)
git add .
git commit -m "estrutura inicial do projeto Node com Express e mysql2"

PHP:

mkdir wedding-pass && cd wedding-pass
git init
mkdir public src
# cria public/index.php com o roteador básico
# cria src/conexao.php com o PDO
# cria .gitignore (seção 5)
git add .
git commit -m "estrutura inicial do projeto PHP com PDO"
php -S localhost:8000 -t public

O esqueleto de código de cada uma (servidor mínimo, conexão com o banco) é assunto do módulo 04. Aqui o ponto é o ritual: pasta → git init → esqueleto → .gitignore → primeiro commit. Sempre nessa ordem, sempre com o Git nascendo junto com o projeto, nunca depois.

2. Versionamento: a máquina do tempo (e a testemunha)

Versionamento é a máquina do tempo do código. Cada vez que você salva um marco (um commit), o Git guarda uma foto do projeto inteiro naquele instante. Você pode voltar pra qualquer foto, comparar o que mudou entre duas, e trabalhar em ideias novas sem medo de estragar o que já funciona.

No mercado isso é inegociável: nenhum time trabalha sem controle de versão. Na prova, são três papéis ao mesmo tempo:

1. Rede de segurança. Quebrou tudo às 3h40 de prova? Volta pro último commit que funcionava e perde minutos, não a prova.
2. Competência avaliada. Os 5% de configuração e versionamento saem direto da qualidade do teu repositório.
3. Evidência de método. A banca pode ler o histórico. Vinte commits pequenos com mensagens claras contam a história de alguém que trabalha com método. Um commit gigante "projeto final" não conta história nenhuma.

3. Os três estados: como o Git enxerga teus arquivos

Aqui mora a base de tudo. Todo arquivo num repositório Git está em um de três lugares:

   Working Directory  ──git add──▶  Staging Area  ──git commit──▶  Repositório
   (teus arquivos,                  (a "área de                   (histórico
    como estão agora)                embarque":                    permanente
                                     o que vai entrar              de commits)
                                     no próximo commit)

• Working directory: os arquivos como estão no teu disco agora, com tudo que você editou e ainda não marcou pra salvar.
• Staging area (área de preparação): a lista do que vai entrar no próximo commit. É uma área de embarque: você escolhe o que sobe.
• Repositório: o histórico permanente. O que foi commitado está guardado e tem um endereço (o hash).

Os comandos que movem os arquivos entre os estados:

git status                  # onde está cada arquivo agora (o comando mais usado do Git)
git add arquivo.js          # move arquivo do working pra staging
git add .                   # move tudo que mudou pra staging
git commit -m "mensagem"    # grava a staging no histórico
git diff                    # o que mudou e AINDA NÃO está na staging
git diff --staged           # o que está na staging e vai entrar no próximo commit

4. Commits que contam história

4.1 A anatomia de um commit

Cada commit guarda: um hash (o endereço único, tipo a3f9c21), o autor (o user.name e user.email que você configurou), a data, a mensagem, e um ponteiro pro commit anterior. Essa corrente de ponteiros é o histórico. Pra ver:

git log                      # histórico completo, um bloco por commit
git log --oneline            # uma linha por commit (o dia a dia)
git log --oneline --graph --all   # o desenho dos branches (seção 7)

4.2 O que faz uma mensagem boa

Uma boa mensagem completa a frase "este commit...": começa com verbo no presente, diz o que mudou e, quando não for óbvio, por quê. É escrita pra alguém ler daqui a duas semanas (e esse alguém é você, ou a banca).

Um padrão leve de prefixo ajuda a bater o olho no git log --oneline e entender o histórico (o mercado chama de conventional commits; pra nós, a versão enxuta basta):

• feat: funcionalidade nova (feat: adiciona dashboard de ocupação)
• fix: correção de bug (fix: corrige mesa que estourava a capacidade)
• style: só visual/CSS (style: alinha cards do dashboard no grid)
• refactor: melhora sem mudar comportamento (refactor: extrai validação pra função própria)
• docs: documentação (docs: adiciona dicionário de dados)

5. .gitignore: o que nunca entra no repositório

Nem tudo que está na pasta do projeto deve ser versionado. Três categorias ficam de fora:

1. O que é gerado/baixado: node_modules/ (Node) e vendor/ (PHP) são reconstruíveis com npm install / composer install. Versionar isso incha o repositório com milhares de arquivos que não são teus.
2. O que é segredo: arquivo .env com senha do banco e chave do JWT. Nunca entra no Git.
3. O que é lixo do sistema: .DS_Store, Thumbs.db, logs.

O .gitignore é um arquivo de texto na raiz do projeto listando o que o Git deve fingir que não existe. O nosso, que serve pras duas stacks:

node_modules/
vendor/
.env
*.log
.DS_Store
Thumbs.db

6. Desfazer sem drama

Errar faz parte; o Git existe pra isso. O mapa de "deu ruim → comando":

7. Branch: linhas de trabalho paralelas

7.1 O conceito

Um branch é uma linha de trabalho paralela. Tecnicamente é só um ponteiro pra um commit (por isso criar branch é instantâneo e de graça), mas na prática é isso: você cria um branch pra desenvolver uma funcionalidade nova sem tocar na versão estável. A main é o tronco, a versão que sempre funciona e da qual sai a demo.

git branch                        # lista os branches (o * mostra onde você está)
git switch -c feature/check-in    # cria o branch E já muda pra ele
git switch main                   # volta pra main
git branch -d feature/check-in    # apaga o branch (depois do merge)

Nomes que se explicam: feature/rsvp-convidado, feature/dashboard, fix/capacidade-mesa. O prefixo diz o tipo, o resto diz o assunto.

7.2 O fluxo que a prova valoriza

O padrão profissional, que é o mesmo que o CIS quer ver:

1. A main está funcionando. Nunca se desenvolve funcionalidade nova direto nela.
2. git switch -c feature/nome-da-funcionalidade
3. Trabalha ali, commitando em marcos pequenos.
4. Funcionou e foi testado? git switch main e git merge feature/nome-da-funcionalidade.
5. A main continua sempre apresentável, e é dela que sai a demo do Módulo D.

8. Merge: juntando as linhas (e resolvendo o conflito real)

8.1 Os dois tipos de merge

Fast-forward: a main não andou desde que o branch nasceu. O Git só desliza o ponteiro pra frente. Sem drama, sem commit extra:

main:     A──B
                \
feature:         C──D        →  merge  →   main: A──B──C──D

Merge commit (three-way): a main também andou enquanto o branch existia. O Git cria um commit de merge que junta as duas linhas:

main:     A──B──────E
                \     \
feature:         C──D──M   ← commit de merge

Os dois são normais e corretos. O merge commit ainda tem um bônus: aparece no git log --graph como prova visual de que você trabalhou com branches.

8.2 Conflito: o que é de verdade

Conflito acontece quando as duas linhas de trabalho mexeram na mesma região do mesmo arquivo e o Git não tem como decidir sozinho qual versão fica. Não é erro, não é castigo: é o Git pedindo uma decisão humana.

Cenário concreto no Wedding Pass: na main você ajustou o limite de convidados por mesa pra 8 no config.js; no branch feature/dashboard, o mesmo arquivo ganhou o limite 10. Na hora do merge:

$ git merge feature/dashboard
Auto-merging config.js
CONFLICT (content): Merge conflict in config.js
Automatic merge failed; fix conflicts and then commit the result.

O Git marca o trecho conflitado dentro do arquivo:

<<<<<<< HEAD
const LIMITE_MESA = 8;        // o que está na main (onde você está)
=======
const LIMITE_MESA = 10;       // o que veio do branch
>>>>>>> feature/dashboard

8.3 Resolvendo, passo a passo

1. Respira. O projeto não quebrou; o Git está esperando você decidir.
2. git status mostra quais arquivos estão em conflito (both modified).
3. Abre o arquivo no VS Code. Ele destaca o trecho e oferece os botões Accept Current (fica o da main), Accept Incoming (fica o do branch) e Accept Both. Ou edita na mão: apaga os marcadores <<<<<<<, =======, >>>>>>> e deixa o código final como deve ser (às vezes a resposta certa é uma mistura dos dois).
4. Testa. Arquivo resolvido tem que rodar. Resolver conflito escolhendo errado compila do mesmo jeito, mas quebra o comportamento.
5. git add config.js e git commit (o Git já sugere a mensagem de merge). Pronto, as linhas se juntaram.

Se enrolar de vez: git merge --abort cancela o merge e devolve tudo pro estado de antes. Ninguém se machucou, tenta de novo com calma.

9. Remoto, GitHub e a tal da nuvem

Tudo até aqui aconteceu no repositório local, na tua máquina. Um remoto (GitHub, GitLab) é uma cópia do repositório hospedada fora dela:

git remote add origin https://github.com/usuario/wedding-pass.git
git push -u origin main       # primeira vez: envia e vincula o branch
git push                      # daí em diante: envia os commits novos
git pull                      # traz o que mudou no remoto
git clone URL                 # baixa um repositório inteiro

Pra nossa realidade:

• No treino: cada uma tem o repositório no GitHub. Serve de backup (a máquina pode morrer, o histórico não), e o professor acompanha a evolução dos commits sem pedir zip pra ninguém.
• Na prova: o que vale é o repositório local bem organizado (confirmando a regra do dia). O remoto é conceito da UC10 e assunto de apresentação: saber explicar como o projeto seria compartilhado num time real.
• Nuvem, no sentido da UC10, é isso: o código e os serviços hospedados fora da tua máquina. GitHub é nuvem pra código; hospedagem de aplicação é assunto do módulo 04 em diante.

10. Integração contínua: o conceito que fecha a UC10

Integração contínua (CI) é a prática de juntar o trabalho de todo mundo no tronco com frequência (diária, no mínimo) e rodar uma verificação automática a cada junção: o servidor de CI pega o código, instala, builda e roda os testes. Quebrou? O time fica sabendo em minutos, não na véspera da entrega. No GitHub isso tem nome de GitHub Actions; um arquivo de configuração no repositório dispara os testes a cada push.

Numa prova individual e curta não tem servidor de CI, mas a disciplina que o CI automatiza é exatamente o nosso ritual manual:

11. Como o CIS pontua versionamento

O versionamento aparece com peso 5%, misturando critério objetivo e julgamento. O mapa completo, agora com a régua 0-3 explícita:

E a régua de julgamento na prática, do zero ao três:

• 0: um commit só ("projeto final"), ou repositório sem histórico útil.
• 1: poucos commits, genéricos ("ajustes", "att"), tudo na main.
• 2: commits frequentes com mensagens razoáveis, mas tudo na main, sem branch.
• 3: commits frequentes com mensagens que contam história, branches por funcionalidade, merges limpos visíveis no git log --graph. O histórico sozinho explica como o projeto foi construído.

12. Autoavaliação do módulo

1. O que precisa estar instalado e testado no ambiente antes de a prova começar, e qual o comando que confere cada item?
2. Qual é o fluxo de montagem de um projeto do zero, na ordem certa, e por que o git init vem antes do código?
3. Explica os três estados do Git e qual comando move um arquivo de cada estado pro próximo.
4. Editei um arquivo, dei git add, editei de novo e commitei. O que foi pro commit e como o git status teria me avisado?
5. O que faz uma boa mensagem de commit? Transforma "mexi no banco" numa mensagem nota 3.
6. Por que node_modules/, vendor/ e .env nunca entram no repositório, e o que fazer se um deles já foi commitado?
7. Qual a diferença entre git restore, git revert e git reset --hard, e qual deles nunca usar sozinho na prova?
8. Qual a diferença entre um merge fast-forward e um merge commit?
9. O que é um conflito de merge, por que ele acontece e quais os 5 passos pra resolver?
10. O que faz o git merge --abort e quando usar?
11. Pra que serve a main-teste no nosso fluxo e o que a main tem que ser sempre?
12. O que é integração contínua e qual é a "versão manual" dela numa prova individual?
13. Descreve um histórico de commits nota 3 e um nota 1 no critério de julgamento do CIS.

Referências do módulo

Bibliografia da UC10 (plano de curso):

• AQUILES, Alexandre; FERREIRA, Rodrigo. Controlando versões com Git e GitHub. Casa do Código.
• SKOULIKARI, Anna. Aprendendo Git. Novatec.

Mercado e documentação:

• Pro Git (livro oficial, em português): O básico de Branch e Merge — o capítulo que cobre as seções 7 e 8 direto da fonte.
• freeCodeCamp: Como escrever boas mensagens de commit — o guia prático por trás da seção 4.
• GitHub Docs: Resolvendo um conflito de merge na linha de comando — o passo a passo oficial do cenário da seção 8.