Git, GitHub, Github Flow e Conventional Commits

No desenvolvimento de qualquer projeto, seja um complexo modelo de machine learning ou um simples script de análise de dados, a organização e o acompanhamento das mudanças no código são cruciais. Já se viu perdido em múltiplas versões de arquivos, como analise_final.py, analise_final_v2.py, analise_final_agora_vai.py? Ou teve receio de testar uma nova abordagem com medo de quebrar o que já funcionava?

Git e GitHub entram em cena como seus maiores aliados nessa jornada! O Git é o sistema de controle de versão que permite registrar cada alteração, voltar no tempo e experimentar sem medo. O GitHub, por sua vez, é a plataforma colaborativa onde você pode hospedar seus projetos, trabalhar em equipe, mostrar seu portfólio e contribuir com a comunidade. Dominar essas ferramentas não é apenas uma habilidade técnica, mas um superpoder que eleva a qualidade, a organização e a colaboração em seus projetos de Ciência de Dados.

Este guia prático irá conduzi-lo através dos conceitos essenciais do Git, mostrar como utilizar o GitHub de forma eficaz, introduzir o fluxo de trabalho ágil GitHub Flow e padronizar suas mensagens de commit com Conventional Commits, preparando você para um desenvolvimento mais profissional e colaborativo.

Instalação e Configuração Inicial do Git no WSL

Como já temos nosso ambiente WSL configurado (Ubuntu, por padrão em nossa oficina), a instalação do Git é feita diretamente dentro da sua distribuição Linux.

Abra o terminal do seu WSL (Ubuntu) e execute os seguintes comandos para instalar o Git:

sudo apt update
sudo apt install git -y

Após a instalação, é crucial configurar seu nome de usuário e e-mail. Essas informações serão associadas a todos os commits que você fizer:

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

Você pode verificar suas configurações com:

git config --list

Essas configurações globais são salvas no arquivo ~/.gitconfig (ou ~/.config/git/config) dentro do seu ambiente WSL. Cada projeto também pode ter configurações locais, que ficam em .git/config dentro do repositório do projeto.

Conceitos Fundamentais do Git

Para utilizar o Git de forma eficaz, é importante entender alguns conceitos básicos:

• Repositório: É o coração do seu projeto quando se usa Git. Ele armazena todos os arquivos do projeto, o histórico completo de todas as alterações, e metadados. Um repositório pode ser local (na sua máquina, dentro do WSL) ou remoto (hospedado em plataformas como GitHub).
• Working Directory (Diretório de Trabalho): A pasta no seu sistema de arquivos (dentro do WSL) onde você efetivamente cria, edita e organiza os arquivos do seu projeto.
• Staging Area (Área de Staging ou Preparação): Uma área intermediária. Antes de registrar permanentemente um conjunto de alterações (fazer um “commit”), você as adiciona à Área de Staging. Isso permite que você escolha quais modificações específicas farão parte do próximo commit.
• Commit: Um “snapshot” (“foto” do seu repositório naquele exato momento) das alterações do seu projeto que foram adicionadas à Staging Area. Cada commit é salvo permanentemente no histórico do repositório, possui um identificador único e é acompanhado de uma mensagem que descreve as alterações realizadas.
• Branch: Uma linha independente de desenvolvimento. Pense nela como uma cópia do seu projeto onde você pode trabalhar em novas funcionalidades ou correções sem afetar a branch principal (comumente chamada de main). Branches são fundamentais para a colaboração e organização.
• Merge: O processo de integrar as alterações de uma branch em outra. Por exemplo, após finalizar uma nova funcionalidade em sua própria branch, você a mesclaria (merge) de volta na branch main.
• Remote (Remoto): Uma referência a um repositório Git que está hospedado em outro lugar, como no GitHub. O nome padrão para o principal repositório remoto conectado ao seu repositório local é origin.
• HEAD: Um ponteiro especial que sempre aponta para o commit mais recente da branch em que você está trabalhando. Ele representa o estado atual do seu projeto.

Fluxo Básico de Comandos Git.
Fonte: https://www.freecodecamp.org (Adaptado)

O Git gerencia seus arquivos através de um ciclo de vida, onde cada arquivo pode estar em um dos seguintes estados:

• Untracked: Arquivos não rastreados, ou seja, arquivos novos que o Git ainda não “conhece”.
• Tracked: Arquivos já rastreados, que podem estar em um dos seguintes subestados:
  • Unmodified: Sem alterações desde o último commit.
  • Modified: Alterados, mas ainda não preparados para o próximo commit.
  • Staged: Modificações adicionadas à Staging Area e prontas para serem commitadas.

Comandos Essenciais do Git no Dia a Dia

Para iniciar um novo projeto com Git, navegue até a pasta do seu projeto no terminal WSL e execute:

git init

Este comando cria um novo subdiretório .git que contém todos os arquivos necessários para o repositório.

Se você quer trabalhar em um projeto que já existe no GitHub, você o clonará para sua máquina local (dentro do WSL):

git clone <URL_do_repositorio_remoto>

Por exemplo: git clone https://github.com/usuario/meu-projeto.git.

O comando que você mais usará é git status. Ele mostra o estado atual do seu diretório de trabalho e da staging area: quais arquivos foram modificados, quais estão na staging area, e quais não estão sendo rastreados pelo Git.

NotaSeu GPS no Git

Pense no git status como seu painel de controle principal. Antes de qualquer git add, git commit, git push, ou git pull, e depois de realizar essas operações, execute git status. Ele dirá exatamente o que mudou, o que está pronto para ser salvo e se você está sincronizado com o repositório remoto. Sempre comece e termine seu trabalho Git com git status para saber onde você está.

Quando você faz alterações nos arquivos, precisa adicioná-las à Staging Area antes de comitá-las:

• git add <nome_do_arquivo>: Adiciona um arquivo específico.
• git add .: Adiciona todas as alterações (arquivos novos e modificados) no diretório atual e subpastas.
• git add -p: Permite revisar e adicionar (“stage”) partes de arquivos interativamente, oferecendo um controle mais granular.

Após preparar as alterações, você as salva no histórico local com um commit:

git commit -m "Mensagem curta e descritiva do commit"

Para modificar o último commit (por exemplo, para corrigir a mensagem ou adicionar um arquivo esquecido), use git commit --amend (mas evite fazer isso em commits que já foram enviados para um repositório remoto compartilhado).

Para visualizar o histórico de commits, use git log. Algumas variações úteis são:

• git log --oneline: Mostra cada commit em uma única linha.
• git log --graph: Exibe o histórico com uma representação gráfica das branches e merges.
• git log --decorate: Mostra os nomes das branches e tags junto aos commits.
• git log --stat: Apresenta estatísticas das alterações em cada commit.

É comum termos arquivos ou pastas que não queremos incluir no controle de versão (como arquivos de dependências, logs, configurações de IDE ou dados sensíveis). Para isso, crie um arquivo chamado .gitignore na raiz do seu projeto e liste os padrões de arquivos e pastas a serem ignorados. Por exemplo: .venv/, renv/, *.log, .env, __pycache__/. Sites como gitignore.io podem ajudar a gerar um arquivo .gitignore adequado para diversas tecnologias.

Para remover arquivos do Git, use git rm <arquivo> (remove do diretório de trabalho e da staging area) ou git rm --cached <arquivo> (remove apenas da staging area, mantendo o arquivo localmente). Para mover ou renomear arquivos, use git mv <nome_antigo> <nome_novo>.

Trabalhando com Branches

Para listar suas branches locais, use git branch (a branch atual será marcada com um *). git branch -r lista as branches remotas que seu Git local conhece, e git branch -a lista todas.

Para criar uma nova branch a partir do seu commit atual:

git branch <nome-da-nova-branch>

Para começar a trabalhar em uma branch, você precisa “mudar” para ela:

git switch <nome-da-branch>

Aviso

Em versões mais antigas do Git, usava-se git checkout <nome-da-branch>. git switch é a forma moderna e mais clara para essa operação.

Um atalho para criar uma nova branch e já mudar para ela é:

git switch -c <nome-da-nova-branch>

Se precisar renomear a branch em que você está:

git branch -m <novo-nome-da-branch>

Após uma branch ter suas alterações integradas (mescladas) à branch principal, você pode deletá-la localmente:

• git branch -d <nome-da-branch>: Deleta a branch (seguro, só funciona se já foi mesclada).
• git branch -D <nome-da-branch>: Força a deleção (use com cuidado).

A mesclagem (merge) é o processo de integrar as alterações de uma branch em outra. Primeiro, vá para a branch que receberá as alterações (ex: main):

git switch main

Em seguida, execute o comando para mesclar a outra branch:

git merge <nome-da-branch-com-as-alteracoes>

Às vezes, o Git não consegue mesclar as alterações automaticamente porque há modificações conflitantes no mesmo trecho de código em ambas as branches. Isso é um conflito de merge. O Git marcará os locais de conflito nos arquivos usando marcadores como <<<<<<< HEAD, =======, e >>>>>>> nome-da-branch-com-as-alteracoes. Você precisará abrir esses arquivos, editar o conteúdo para manter o código desejado, remover esses marcadores, salvar, adicionar os arquivos resolvidos (git add <arquivo-resolvido>) e, finalmente, finalizar o merge com git commit. Se um merge se mostrar muito complicado, você pode abortá-lo com git merge --abort.

Colaborando com Repositórios Remotos (GitHub)

Plataformas como GitHub, GitLab ou Bitbucket hospedam repositórios Git na web, facilitando a colaboração, o backup e o gerenciamento de projetos. Elas oferecem ferramentas adicionais como Pull Requests, Issues (para rastrear tarefas e bugs), Actions (para automação de CI/CD), Wikis e muito mais. Vamos focar no GitHub.

Importante

Antes de prosseguir, certifique-se de que sua conta GitHub está configurada corretamente no WSL. Se ainda não fez essas configurações, consulte a Seção de Dicas para um guia detalhado.

Para ver quais repositórios remotos estão configurados para seu projeto local:

git remote -v

Quando você clona um repositório, o Git automaticamente configura um remoto chamado origin apontando para a URL de onde você clonou. Se você iniciou um repositório localmente (git init) e quer conectá-lo a um novo repositório que você criou no GitHub:

git remote add origin <URL_do_seu_repositorio_no_GitHub>

Exemplo: git remote add origin https://github.com/seu-usuario/seu-projeto.git

Para enviar seus commits locais para o repositório remoto:

git push <nome-do-remoto> <nome-da-branch>

Comumente: git push origin main. Na primeira vez que você envia uma nova branch para o remoto, pode usar git push -u origin <nome-da-branch> para configurar o rastreamento (upstream), de forma que nas próximas vezes um simples git push seja suficiente para essa branch.

Para buscar as alterações mais recentes do repositório remoto (novos commits, novas branches) sem integrá-las imediatamente ao seu diretório de trabalho local:

git fetch <nome-do-remoto>

Isso atualiza suas “cópias” locais das branches remotas (ex: origin/main).

Para buscar as alterações E integrá-las (mesclá-las) à sua branch local atual:

git pull <nome-do-remoto> <nome-da-branch>

Comumente, se você está na branch main e quer atualizá-la com as mudanças do origin: git pull origin main. Este comando é, na verdade, uma combinação de git fetch seguido por git merge origin/main (por padrão). Muitos desenvolvedores preferem fazer git fetch e depois inspecionar as alterações antes de fazer git merge ou git rebase manualmente, para ter mais controle.

Dicas

NotaConventional Commits: Mensagens que Contam uma História

Conventional Commits é uma convenção simples sobre como escrever suas mensagens de commit. Ela adiciona uma estrutura leve que torna as mensagens legíveis tanto por humanos quanto por máquinas, trazendo diversos benefícios.

A estrutura básica é:

<tipo>[escopo opcional]: <descrição concisa>

[corpo opcional com mais detalhes, explicando o PORQUÊ da mudança]

[rodapé opcional para BREAKING CHANGE, ou referências a Issues (ex: Closes #123)]

Tipos Comuns:

• feat: Introduz uma nova funcionalidade para o usuário (correlaciona com MINOR em versionamento semântico).
• fix: Corrige um bug no código que afeta o usuário (correlaciona com PATCH em versionamento semântico).
• docs: Alterações exclusivamente na documentação (ex: README, guias).
• style: Mudanças que não afetam o significado do código (formatação, espaços, ponto e vírgula, etc.).
• refactor: Uma reescrita de código que não corrige um bug nem adiciona uma funcionalidade, mas melhora a estrutura interna.
• test: Adição de testes que faltavam ou correção de testes existentes.
• build: Mudanças que afetam o sistema de build ou dependências externas (ex: Webpack, npm, arquivos de Docker).
• ci: Mudanças nos arquivos e scripts de configuração de Integração Contínua (ex: GitHub Actions workflows).
• chore: Outras alterações que não modificam o código-fonte ou arquivos de teste (ex: atualização de tarefas de build, configuração de ferramentas).
• BREAKING CHANGE: Uma alteração que introduz uma incompatibilidade com versões anteriores (correlaciona com MAJOR em versionamento semântico). Pode ser indicada adicionando um ! após o tipo/escopo (ex: refactor!: ... ou feat!: ...), e DEVE ser explicada no rodapé do commit.

Para indicar uma Breaking Change (uma alteração que quebra a compatibilidade com versões anteriores), adicione um ! após o tipo/escopo. O rodapé do commit DEVE conter uma seção BREAKING CHANGE: explicando a alteração e como migrar. Exemplo: refactor!: remove deprecated API endpoint. Uma breaking change correlaciona com MAJOR em versionamento semântico.

Benefícios:

• Geração Automática de Changelogs: Ferramentas podem ler os commits e gerar listas de mudanças (changelogs) automaticamente.
• Versionamento Semântico Facilitado: Ajudam a determinar automaticamente qual parte da versão de um software deve ser incrementada (MAJOR, MINOR, PATCH).
• Melhor Compreensão do Histórico: Tornam o histórico de commits muito mais fácil de entender para todos os colaboradores (e para o seu “eu” do futuro).
• Comunicação na Equipe: Melhoram a comunicação sobre a natureza das mudanças.
• Automatização: Permitem que commits específicos disparem processos de build, teste ou deploy em sistemas de CI/CD.

Exemplo:

feat: adiciona gráfico para análise da variável de orçamento

Implementa um novo gráfico utilizando ggplot2 para visualizar tendências, 
padrões e outliers na variável de orçamento do conjuntos de dados da
folha de 2023.

---

Nem sempre vamos precisar utilizar o padrão completo, na maioria das vezes apenas o commit com o padrão de mensagem <tipo>[escopo opcional]: <descrição concisa> já é excelente!

NotaGitHub Flow: Um Fluxo de Trabalho Ágil

O GitHub Flow é um fluxo de trabalho leve, baseado em branches, e muito popular, especialmente para projetos que praticam entrega contínua ou que desejam um processo simples e direto.

Metodologia Github Flow.

Seus princípios fundamentais são:

1. A branch main é sempre “deployable” (implantável): O código na main deve estar sempre estável, testado e pronto para ir para produção a qualquer momento.

2. Crie Branches Descritivas a partir de main: Para qualquer novo desenvolvimento (uma nova funcionalidade, uma correção de bug, um experimento), crie uma nova branch a partir da versão mais recente da main. Dê um nome claro e descritivo para a branch (ex: fix/api-dados-bug, feat/add-linear-model).

   git switch main
   git pull origin main # Garante que sua 'main' local está sincronizada com o remoto
   git switch -c nova-feature-descritiva

3. Adicione Commits Localmente e Envie para o Remoto Regularmente: Faça commits pequenos e focados na sua branch de feature. Envie suas alterações para a branch correspondente no repositório remoto (no GitHub) com frequência. Isso não apenas faz backup do seu trabalho, mas também o torna visível para outros colaboradores, se houver.

   # ... faça suas alterações ...
   git add .
   git commit -m "feat: implementa parte X da nova feature" # Usando Conventional Commits!
   git push origin nova-feature-descritiva

4. Abra um Pull Request (PR): Quando sua funcionalidade estiver pronta para revisão, ou mesmo se você quiser um feedback inicial sobre o trabalho em progresso, abra um Pull Request (PR) no GitHub. O PR é o ponto central para discussão e revisão do código. Nele, você compara sua feature branch com a main.

5. Discuta e Revise o Código: Colaboradores (ou você mesmo, revisando seu próprio trabalho) analisam as alterações, fazem comentários, sugerem melhorias e tiram dúvidas. Ferramentas de análise estática e testes automatizados (configurados via GitHub Actions, por exemplo) também rodam aqui para garantir a qualidade.

6. Faça Deploy para Testes (Opcional, mas Comum): Muitas equipes configuram seus sistemas para fazer deploy automaticamente da branch do PR para um ambiente de testes/staging. Isso permite verificar as alterações em um ambiente real antes de integrá-las à main.

7. Mescle (Merge) na main após Aprovação e Testes: Uma vez que o PR é aprovado (LGTN - “Looks Good To Me!”), todos os testes passam e as discussões são resolvidas, ele é mesclado na branch main.

   • Importante: No GitHub, ao mesclar um PR, você frequentemente terá opções como “Squash and merge” ou “Rebase and merge”. “Squash and merge” combina todos os commits da feature branch em um único commit na main, o que é popular porque mantém o histórico da main mais limpo e linear, facilitando a leitura do histórico de versões principais.
   • Após o merge bem-sucedido, a feature branch já cumpriu seu propósito e pode ser deletada tanto no repositório remoto (o GitHub geralmente oferece um botão para isso após o merge) quanto localmente.

   # Após o merge no GitHub:
   git switch main
   git pull origin main # Atualiza sua 'main' local com o merge
   git branch -d nova-feature-descritiva # Deleta a branch local, pois já foi integrada

As vantagens do GitHub Flow incluem sua simplicidade, clareza, e como ele promove a integração contínua e deploys frequentes. Pull Requests são centrais, incentivando a revisão de código e a colaboração.

É importante mencionar o Gitflow, um modelo de branching mais antigo e estruturado, com branches dedicadas como develop, feature/*, release/*, e hotfix/*. Embora o Gitflow seja robusto para projetos com ciclos de release mais longos e formais, para muitos projetos modernos, especialmente aqueles com integração e entrega contínuas (CI/CD), o GitHub Flow (ou fluxos similares como o GitLab Flow) oferece uma abordagem mais ágil, direta e simplificada.

NotaConfiguração de Acesso Seguro ao GitHub

Para interagir com seus repositórios no GitHub a partir do seu ambiente WSL, você pode usar HTTPS ou SSH. A forma mais simples e recomendada atualmente é utilizar a CLI do GitHub (gh) para autenticar.

• HTTPS: Envolve URLs como https://github.com/usuario/repositorio.git. Tradicionalmente, exigia o uso de senhas ou Personal Access Tokens (PATs).
• SSH: Envolve URLs como git@github.com:usuario/repositorio.git. Utiliza um par de chaves criptográficas para uma autenticação mais segura e conveniente no dia a dia.

Autenticando com a GitHub CLI (Recomendado):

A GitHub CLI (gh) simplifica o processo de autenticação com o GitHub, seja via HTTPS ou SSH. Se você ainda não tem a GitHub CLI instalada, você pode seguir as instruções de instalação para Linux (WSL) no site oficial da CLI do GitHub.

Após a instalação, o comando gh auth login guiará você por um processo interativo no navegador para autenticar sua conta do GitHub. Ele pode configurar automaticamente suas credenciais Git para usar HTTPS ou configurar suas chaves SSH.

1. Instale a GitHub CLI: Siga as instruções em https://github.com/cli/cli/blob/trunk/docs/install_linux.md. Para o Ubuntu (WSL), os comandos são:

   (type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
       && sudo mkdir -p -m 755 /etc/apt/keyrings \
           && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
           && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
       && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
       && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
       && sudo apt update \
       && sudo apt install gh -y

2. Autentique-se: Execute o comando abaixo e siga as instruções.

   gh auth login

   • Você será perguntado com qual conta do GitHub deseja se autenticar (github.com ou GitHub Enterprise).
   • Você será perguntado qual o seu protocolo preferido para operações Git (HTTPS ou SSH). Se escolher SSH e não tiver uma chave configurada, a CLI poderá ajudar a gerar uma nova e enviá-la para sua conta do GitHub.
   • Você precisará se autenticar no seu navegador.

Após completar o gh auth login, a CLI do GitHub e o Git estarão configurados para interagir com o GitHub sem a necessidade de configurar manualmente PATs ou chaves SSH como descrito nas seções anteriores (que foram removidas para simplificar).

Se por algum motivo você precisar configurar o acesso manualmente (por exemplo, em ambientes onde não pode usar gh auth login), as seções sobre configuração manual de SSH e PATs foram removidas deste guia, mas podem ser encontradas na documentação oficial do GitHub. No entanto, para a maioria dos usuários no WSL, gh auth login é a abordagem recomendada.

Conclusão

Dominar Git e GitHub é uma habilidade transformadora para qualquer pessoa que trabalha com código, especialmente em ciência de dados, onde a reprodutibilidade e a colaboração são fundamentais. O Git oferece o poder de gerenciar o histórico do seu trabalho, enquanto o GitHub fornece a plataforma para colaborar, compartilhar e construir projetos de forma eficaz. Adotar um fluxo de trabalho como o GitHub Flow, juntamente com a disciplina dos Conventional Commits, trará clareza, organização e eficiência para seus projetos. A prática constante é a chave para solidificar esses conhecimentos e torná-los parte natural do seu dia a dia.

Recursos Adicionais

• Site Oficial do Git (Documentação e o livro Pro Git)
• Documentação do GitHub
• Conventional Commits Specification
• Learn Git Branching (Tutorial Interativo)
• GitHub Flow Guide (Documentação Oficial do GitHub)