3  Módulo 2 | Data Science Collaboration tools: Github

4 Colaboração e Data Science (Controlo de versões)

4.1 O que é o Controlo de Versões?

O controlo de versões é um sistema que regista as alterações feitas a um ficheiro ou a um conjunto de ficheiros ao longo do tempo. Os objetivos deste registo serve várias funções, mas a mais importante seráa de recuperar versões específicas mais tarde e de poder gerir múltiplas versões do mesmo ficheiro.

Durante o processo de análise dados para detetar insights, iremos ter um processo iterativo de exploração de dados e será relavante guardar todas as versões do seu script de análise. Um Sistema de Controlo de Versões (SCV) permite fazer exatamente isso de forma robusta e organizada.

Com um SCV, podemos:

• Reverter ficheiros específicos ou o projeto inteiro para um estado anterior;
• Comparar as alterações ao longo do tempo;
• Ver quem modificou o quê, e quando, algo é crucial para encontrar a origem de um problema;
• Recuperar facilmente o seu trabalho se cometer um erro grave ou perder ficheiros.

4.1.1 Tipos de Sistemas de Controlo de Versões

Existem várias abordagens para o controlo de versões:

1. Sistemas Locais: A abordagem mais básica é copiar ficheiros para outra pasta (ex: projeto_v2, projeto_final_mesmo). É simples, mas muito propenso a erros. É fácil esquecer-se em que pasta está o ficheiro mais recente e manter um registo ativo das alterações feitas entretanto. Existem sistemas melhores como o RCS que guardam a diferença entre ficheiros para poder ser recriado uma versão anterior (Chacon e Straub 2014)

Diagrama de um sistema de controlo de versões local

2. Sistemas Centralizados (CVCS): Sistemas como o Subversion e o Perforce usam um único servidor central que contém todos os ficheiros versionados. Os utilizadores (clientes) fazem “check-out” dos ficheiros desse servidor. Um exemplo mais familiar à Saúde seria uma pasta do OneDrive.

Diagrama de um sistema de controlo de versões local

Vantagem:

• Todos na equipa sabem o que os outros estão a fazer, e os administradores têm controlo total.

Desvantagem:

• Único ponto de falha (Servidor);
• Sem internet não é possível sincronizar e na resincronização podem existir conflitos entre colaboradores;
• Se o disco do servidor deixar de funcionar e não houver backups, perde-se tudo.

3. Sistemas Distribuídos (DVCS): É aqui que o Git entra. Num DVCS, os clientes não fazem apenas o check-out da última versão dos ficheiros que têm, mas sim replicam um histórico do repositório.

Vantagens:

• Cada instância do git é um backup completo de todos os dados e do histórico das alterações.
• Se o servidor principal falhar (ex: o Github.com estiver em baixo), qualquer um dos backups dos utilizadores pode ser copiado de volta para um servidor novo para o restaurar. (Alta resiliência e robustez)

Desvantagens:

• Maior complexidade inicial para configurar e manter atualizado se configurado em remote.

Diagrama de um sistema de controlo de versões distribuído como o Git.

4.2 O que é o Git?

A grande diferença do Git é a forma como ele “pensa” nas alterações de dados. Muitos sistemas de controlo de versões armazenam a informação como uma lista de alterações feitas em cada ficheiro. O Git pensa nos seus dados mais como uma série de fotos de um mini sistema de ficheiros.

Num commit, o Git guarda o estado do projeto tirando uma “fotografia” do aspeto de todos os seus ficheiros nesse momento e armazena uma referência a essa fotografia.

Quandos os ficheiros não mudam de uma fotografia para outra o Git guarda uma referência à última alteração.

O Git armazena os dados como snapshots do projeto ao longo do tempo.

Operações Locais e Rápidas: Como temos o histórico completo do projeto na pasta git, a maioria das operações (como ver o histórico ou comparar versões) é quase instantânea e corre de forma local na “nossa” cópia local.

Integridade de Dados: Existe um processo de validação denominado de checksum antes do ficheiro ser armazenado baseado no conteúdo e a estrutura da pasta onde o Git se encontra. Isto significa que é impossível alterar o conteúdo de qualquer ficheiro ou diretório sem que o Git saiba.

Centrado na Contínua Adição de Conteúdo: Quase todas as ações no Git apenas adicionam dados à base de dados do Git. É muito difícil perder trabalho que já foi “fotografado”.

4.3 Os Três Estados do Git

A distinção destes 3 estados é crucial para trabalhar com o Git eficazmente. Exitem 3 grandes estados nos quais os ficheiros podem estar: 1. Ficheiros modificado: Significa que existem alterações de um ficheiro, mas ainda não foram guardadas na base de dados do Git local. Estas são as alterações na sua pasta de trabalho. 2. Preparado (Staged): Significa que marcou um ficheiro modificado na sua versão atual para fazer parte do seu próximo commit (a próxima fotografia “snapshot”). 3. Depositados (Committed): Significa que os dados estão guardados de forma segura na sua base de dados local do Git.

Existem também três áreas de trabalho distintas:

1. A Pasta de Trabalho (Working Directory): É uma cópia de uma versão do projeto. É a pasta no seu computador onde pode ver e editar os ficheiros.
2. A Área de Preparação (Staging Area): É um ficheiro, geralmente contido no diretório Git local, que armazena informações sobre o que vai entrar no próximo commit. É uma área intermédia.
3. O Diretório Git (Repositório): É onde o Git armazena os metadados e a base de dados para o projeto.

As três áreas: Pasta de Trabalho, Área de Preparação e Pasta Git.

O fluxo de trabalho básico do Git seria o seguinte:

1. Modifica ficheiros numa pasta de trabalho.
2. Prepara os ficheiros (faz stage ), adicionando as alterações dos mesmos para a sua área de preparação. No GitHub Desktop, isto é feito ao selecionar os ficheiros que quer incluir no commit.
3. Faz um commit, que pega nos ficheiros tal como estão na área de preparação e armazena essa fotografia/ snapshot permanentemente no seu diretório Git.

No geral o Git é frequentemente utilizado no terminal ou linha de comandos. O foco deste curso será uma introdução à utilização às ferramentas com interface gráfica.

O GitHub disponibiliza clientes desktop para Windows e Mac que incluem um interface gráfico para as ações mais comuns.

Estes clientes também incluem ferramentas para a linha de comandos para cenários mais avançados.

::: {.callout-note collapse=“true”, title=“Comandos de Terminal Gerais”}

Aqui estão os comandos no terminal que correspondem a este fluxo:

1. Depois de modificar os ficheiros, usa-se git status para ver o que foi alterado. Mostra os ficheiros na working directory que foram modificados.
2. Para adicionar ficheiros à staging area, usa-se git add nome_do_ficheiro.R. Se executar git status novamente, verá que o ficheiro passou para a secção “Changes to be committed”.
3. Para fazer o commit, usa-se git commit -m "Mensagem descritiva do commit".

Para além destes comando poderão serpre utilizar o git help <verb> para termos as decrição :::

Neste módulo, iremos focar-nos exclusivamente no GitHub Desktop, mas é útil entender a teoria por detrás da ferramenta Git.

5 GitHub

5.1 O que é?

O Github é a maior plataforma de armazenamento remoto de repositórios Git, permitindo a colaboração entre milhões de programadores e projetos. Para além de ter em sido contido uma versão do sistema Git, tem múltiplas funcionalidades úteis como a manutenção de problemas ( issues ), revisão de código, publicação de websites e livros entre outros.

Git e Github não são a mesma coisa

::: {.callout-note collapse=“false”, title=“Utilidade dos sitemas de GIT e GITHUB na ciência de dados”}

Usar Git e GitHub pode parecer complexo no início, mas os benefícios para um cientista de dados são enormes:

1. Reprodutibilidade: Garante que qualquer pessoa (incluindo o seu “eu” do futuro) consegue reproduzir a sua análise. Um histórico claro de alterações mostra exatamente que código e que dados geraram os seus resultados.
2. Colaboração Simplificada: Permite que trabalhe em equipa no mesmo projeto sem o caos de enviar ficheiros por email. Cada pessoa pode trabalhar na sua cópia, e o Git ajuda a juntar ( merge ) as alterações de forma inteligente.
3. Segurança e Backup: Ao guardar o seu trabalho no GitHub, tem um backup automático na nuvem. Se o seu computador avariar, o seu projeto está seguro.
4. Portfólio Profissional: O seu perfil no GitHub serve como um portfólio dinâmico. Empregadores podem ver os seus projetos, a qualidade do seu código e a sua capacidade de colaboração.

:::

5.2 Configuração Inicial (Apenas uma vez)

Antes de começar, precisa de uma conta no GitHub e de instalar o GitHub Desktop.

5.2.1 Criar uma conta no GitHub:

Para começarmos a usar o GitHub, precisamos de criar uma conta pessoal gratuita. Esta conta será a vossa identidade na plataforma. Cada utilizador tem: - Nome de utilizador; - Perfil pessoal; - Endereço de e-mail verificado.

Para começarmos devemos visitar github.com e criar uma conta gratuita. Escolham um nome de utilizador profissional, uma vez que em todos os vossos commits, este será o nome na autoria dos commits.

### Criação de Chave para ligar computador ao Github (Opcional)

Esta secção foi criada para os utilizadores que queiram ter um pouco mais de informação e queriam maior flexibilidade de trabalho com o Github.

Como explicado em cima, os projetos no GitHub privado são como um cofre pessoal. Não é desejável que qualquer pessoa possa abrir esse cofre e mexer nos seus dados e nos projetos. Neste sentido, sempre que o seu computador tenta enviar (um push) ou receber (um pull) código, o GitHub pergunta: “Quem somos e se temos permissão para fazer isto?”.

Existem dois métodos principais para criar esta ligação segura:

1. HTTPS com um Personal Access Token (PAT): Este método é como ter uma palavra-passe específica e descartável para uma aplicação. É o método que recomendamos pela sua simplicidade e segurança.
2. SSH (Secure Shell): Este método é como ter um conjunto de chaves criptográficas (uma pública e uma privada) que funcionam como uma fechadura e a sua chave correspondente. É muito seguro, mas envolve um pouco mais de configuração.

5.2.1.1 Autenticação com HTTPS e um Personal Access Token (PAT)

Um Personal Access Token (ou PAT) é uma alternativa mais segura à palavra-passe. É uma longa cadeia de caracteres que funciona como uma palavra-passe, mas com algumas vantagens importantes:

• É específica: Você cria um PAT para um propósito específico (ex: “para usar no RStudio no meu portátil”).
• Tem permissões limitadas: Você pode escolher exatamente o que um específico PAT pode fazer (ex: apenas aceder a repositórios, mas não apagar).
• É revogável: Se perder o seu portátil, pode simplesmente revogar (cancelar) o PAT no site do GitHub sem ter de mudar a sua palavra-passe principal.

Criação de Personal Acess Token.

Ao tentarem criar irá abrir uma nova página no vosso browser, já na secção de criação de tokens do GitHub. Podem seguir estes passos na página web:

1. Note: Dê um nome descritivo ao seu token. Por exemplo: RStudio no meu Portátil. Isto ajuda a lembrar-se para que serve este token.
2. Expiration: Escolha uma data de expiração. É uma boa prática de segurança não criar tokens que durem para sempre. 30 ou 90 dias é uma escolha sensata. O GitHub irá enviar um email antes de expirar.
3. Scopes: Esta é a parte mais importante. “Scopes” definem o que o token tem permissão para fazer. Para o nosso trabalho de versionamento de código, selecione a caixa repo. Isto dará ao token permissão para aceder, ler e escrever nos seus repositórios.

Comandos de R Correspondentes

install.packages("usethis")
install.packages("gitcreds")

usethis::create_github_token()
gitcreds::gitcreds_set()

5.2.1.2 Autenticação com Chaves SSH (Alternativa)

Esta é uma alternativa poderosa e muito usada por developers. O conceito baseia-se num par de chaves:

• Chave Privada: Fica guardada secretamente no vosso computador.
• Chave Pública: Pode ser partilhada e é colocada no GitHub para identificar o seu computador.

A chave pública funciona como um cadeado que se instala no GitHub, e a chave privada é a única chave que consegue abrir esse cadeado.

Este resumo apenas pretende que saibam que estas opções existem, não sendo esta a forma como iremos trabalha com o Github nesta fase.

5.3 A Nossa Ferramenta: GitHub Desktop

Embora possa usar o Git através de linhas de comando, existe uma forma muito mais visual e intuitiva de o fazer: o GitHub Desktop.

Como já foi referido anteriormente iremos focar a interface gráfica do GitHub Desktop por ser de mais fácil interação para quem está a começar.

Instalar o GitHub Desktop: Descarregue e instale a aplicação a partir de desktop.github.com.

Download do GitHub Desktop para Windows ou Mac.

Fazer Login e Configure o Git:

• Abra o GitHub Desktop. A primeira vez, ele pedirá para fazer login com a sua conta GitHub.
• De seguida, ele pedirá para configurar o seu nome (user.name) e email (user.email) para o Git.

É crucial que use o mesmo email da sua conta GitHub. Esta configuração identifica quem fez cada alteração. O GitHub Desktop trata disto por si.

Será pedido para fazerem o login e depois já estarão conectados

O GitHub Desktop é uma aplicação gratuita que simplifica o uso do Git, abstraindo estes três estados numa interface gráfica simples, onde as suas alterações são visíveis e os passos de stage e commit são combinados numa única ação.

A interface do GitHub Desktop para Windows.

5.4 Criar Primeiro Projeto com GitHub Desktop

Agora iremos tentar pôr-vos a trabalhar. Este guia irá acompanhar-vos desde a criação de um novo repositório até à publicação do seu primeiro projeto no GitHub,usando apenas o GitHub Desktop.

5.4.1 Passo 1: Criar o primeiro repositório

Um repositório (ou “repo”) é simplesmente uma pasta que contém todos os ficheiros do seu projeto, juntamente com o seu histórico de alterações.

Vamos criar um novo repositório no seu computador.

1. Abra o GitHub Desktop e terão 3 opções.

• Novo repositório: Cria novo repositório a nível local

  

  Novo Repositório local

• Adicionar novo repositório local em que podem adicionar o Git a um repostitório que já tenham no vosso computador.

• Clonar um repositório, que significa criar uma cópia completa de um repositório Git existente, incluindo o histórico de commits, os ramos, os arquivos do projeto e as configurações.

Clonar repositório

2. Para já vamos criar um novo repositório e vamos preencha os campos:

• Name: Vamos um nome curto e descritivo ao seu projeto (ex:primeiro-projeto-ds).
• Description: Uma frase que descreva o projeto.
• Local Path: A pasta no seu computador onde o repositório será guardado. Escolha um local de fácil acesso (ex: Documentos/GitHub).
• Initialize this repository with a README: Marque esta opção. Um ficheiro README.md é o “cartão de visita” do seu projeto e é boa prática colocar para facilitar quem visita .
• Git Ignore: Selecione R na lista. Isto cria um ficheiro .gitignore que diz ao Git para ignorar ficheiros temporários e desnecessários comuns em projetos de R.
• License: Escolha uma licença, se aplicável (ex: MIT License). Uma licença define como outras pessoas podem usar o seu código.

Criação do Repositório Teste

3. Clique em Create Repository.

Parabéns, acabaram de criar o seu primeiro repositório Git no seu computador!

Poderão neste momento: - Publicar o repositório no GitHub - Abrir a pasta do projeto num editor (Notepad++, VScode ou o Rstudio) - Ver a pasta do Projeto no Explorador ou no Finder

Opções num novo projeto

Comandos de Terminal Correspondentes

A criação de um repositório no terminal envolve alguns passos:

1. Navegar até à pasta do seu projeto.

cd "C:/Users/SeuUtilizador/Documents/GitHub/primeiro-projeto-ds"

2. Inicializar o repositório. Este comando cria a subpasta .git oculta que contém toda a magia.

git init

3. Adicionar todos os ficheiros iniciais (README.md, .gitignore, etc.) à área de preparação ( staging area ).

  git add .

O . é um atalho para “todos os ficheiros nesta pasta”.

5.4.2 Passo 2: O Ciclo de Trabalho: Fazer Alterações e Commits

Agora que o repositório está criado, vamos seguir o ciclo de trabalho que vimos anteriormente.

1. Faça uma alteração:

• Abra a pasta do projeto no seu computador (o GitHub Desktop tem um atalho “Show in Explorer” / “Show in Finder”).
• Abra o ficheiro README.md com um editor de texto (como o RStudio, VS Code, ou Bloco de Notas) e adicione uma linha de texto, por exemplo: “Este é o meu primeiro projeto de Data Science com Git!”.
• Grave o ficheiro.

2. Reveja e prepare as alterações (Stage):

• Volte ao GitHub Desktop. A interface irá mostrar-lhe as alterações que fez. Os ficheiros alterados aparecem na barra lateral esquerda. O painel principal mostra a vermelho o que foi removido e a verde o que foi adicionado.
• O GitHub Desktop seleciona automaticamente (stages) todas as alterações por defeito. Se quiser incluir apenas algumas, pode desmarcar os ficheiros que não quer incluir no seu commit.

3. Faça o Commit:

• Na parte inferior esquerda, encontrará a área de commit.
• No campo Summary (required), vamos escrever uma mensagem curta e clara que descreva a alteração. Ex: Adiciona descrição inicial ao README.
• (Opcional) No campo Description, pode adicionar mais detalhes.
• Clique no botão azul Commit to main.

O seu commit está agora guardado no histórico do seu repositório local. main é o nome do ramo (branch) principal do seu projeto.

Histórico do vosso repositório

Comandos de Terminal Correspondentes

1. Para ver as alterações que fez (o que está modified mas não staged), use git status.
2. Para ver exatamente o que mudou no conteúdo dos ficheiros, use git diff.
3. Para adicionar as suas alterações à área de preparação, use git add README.md.
4. Para fazer o commit, use git commit -m "Adiciona descrição inicial ao README".

Agora também poderão ver o opções que estão disponíveis para a linha temporal tais como: 1. Resetar Commit (Reset)

Volta no tempo e remove definitivamente um ou mais commits do histórico atual.
Útil para: apagar commits locais antes de enviar para o servidor.

2. Checkout Commit

Permite aceder ao conteúdo de qualquer commit específico.
Temos acesso de leitura ao estado do projeto naquele ponto do tempo.
Útil para: testes, builds antigos ou análise.

3. Reorder Commit

Mudar a ordem dos commits.
Permite que reorganizes a sequência de commits locais (com rebase -i).
Altera o histórico, então só deve ser feito em commits ainda não enviados para o servidor remoto (GitHub).
Útil para: limpezas antes do push, reorganizar lógica do histórico.

4. Revert Changes in commit

Criado um novo commit que desfaz as alterações feitas num commit anterior.
Seguro porque não reescreve o histórico.
Útil para: desfazer erros sem reescrever commits.

5. Create branch from commit

Cria uma nova linha de desenvolvimento a partir de um commit específico.
Muito útil quando queres explorar uma ideia a partir de um ponto antigo do projeto
Útil para: debugging, hotfixes ou provas de conceito a partir de pontos antigos

6. Create Tag

Cria uma marca permanente num commit.
Tags servem para identificar versões, releases ou marcos importantes. Exemplo: v1.0, beta-2, etc.
Útil para: gerar builds de produção, marcar versões importante

7. Cherry pick commit

Permite escolher um commit de qualquer ramo e "copiar" as alterações para a branch atual.
Cria um novo commit com o conteúdo daquela alteração.
Útil para: aplicar só uma funcionalidade ou correção sem a branch toda.

Histórico do vosso repositório

5.4.3 A Arte de Escrever Boas Mensagens de Commit

A mensagem de commit é um dos aspetos mais importantes de um bom fluxo de trabalho e na colaboração. Ela explica o porquê de uma alteração.

Uma mensagem bem escrita é uma ajuda imensa para os seus colegas e para o seu “eu” do futuro.

Regras para uma boa mensagem (Summary):

1. Seja breve e descritiva: O sumário deve ter cerca de 50 caracteres.
2. Use o modo imperativo: Escreva como se estivesse a dar uma ordem. Isto é uma convenção.
   • Bom: Adiciona script de limpeza de dados
   • Mau: Adicionei o script de limpeza ou Script de limpeza adicionado
3. Seja específico:
   • Bom: Corrige erro de cálculo na média de idade
   • Mau: Correções ou Bug fix

Exemplos de Mensagens de Commit em Ciência de Dados:

Bom (Sumário)	Mau
Adiciona gráfico de dispersão de peso vs. altura	Gráfico novo
Remove colunas duplicadas do dataset de clientes	Limpeza de dados
Altera o modelo de regressão para RandomForest	Update do modelo
Aumenta o tamanho da fonte nos eixos do gráfico	Ajustes
Corrige erro na importação de ficheiros CSV com ;	Erro corrigido
Adiciona documentação da função 'calculate_mean'	Docs

No campo Description (opcional no GitHub Desktop), pode adicionar mais detalhes se a alteração for complexa.

::: {.callout-note collapse=“true title=”Comando de Terminal para Commit”} No terminal, um commit com sumário e descrição seria assim:

git commit -m "Adiciona script de limpeza de dados" -m "O script remove valores NAs das colunas 'idade' e 'salário' e converte a coluna 'data_registo' para o formato datetime."

:::

5.4.4 Passo 3: Publicar o seu repositório no GitHub

Até agora, o seu projeto só existe no seu computador. Vamos publicá-lo para que fique guardado online no seu perfil do GitHub.

1. No GitHub Desktop, verá uma mensagem a dizer “Publish repository to GitHub”. Clique no botão azul Publish repository.

O botão para publicar o repositório no GitHub.

2. Na janela que aparece:

• Confirme o Name e a Description.
• Keep this code private: Desmarque esta opção se quiserem que o seu projeto seja público e faça parte do seu portfólio.
• Clique em Publish Repository.

O GitHub Desktop irá enviar todos os seus ficheiros e o histórico de commits para o GitHub. Se visitar o seu perfil em github.com/seu-username, verão lá o seu novo repositório!

O Primeiro Projeto no GitHub.

Comandos de Terminal Correspondentes

Publicar um repositório local para o GitHub pela primeira vez envolve dois passos:

1. Adicionar o repositório remoto: Tem de dizer ao seu Git local qual é o URL do repositório no GitHub. origin é o nome padrão para o seu repositório remoto principal.

::: {.cell}

```{.bash .cell-code}
git remote add origin https://github.com/seu-username/primeiro-projeto-ds.git
```
:::

2. Fazer o “Push” inicial: Enviar o seu ramo main para o remoto origin. O -u estabelece uma ligação para que futuros push e pull sejam mais simples.

git push -u origin main

5.4.5 Passo 4: O Ciclo Interno Continua (Commit & Push)

O seu projeto está agora online. E se fizer mais alterações? O ciclo é quase o mesmo.

Nova Tarefa: 1. Modificar um ficheiro localmente (por exemplo, adicione mais texto ao README.md). 2. Faça o Commit dessa alteração no GitHub Desktop (com uma nova mensagem, ex: Detalha objetivos do projeto). Agora, o seu repositório local está um commit à frente do repositório no GitHub. O GitHub Desktop mostra-lhe isso. 3. Faça o Push: Clique no botão Push origin para enviar o seu novo commit para o GitHub.

O botão “Push” para enviar commits para o GitHub.

Este é o ciclo essencial para trabalhar sozinho: Modificar -> Commit -> Fazer Push.

Comandos de Terminal Correspondentes

Depois de fazer um novo commit, para o enviar para o GitHub, o comando é mais simples:

git push

Para ver o histórico de commits, pode usar:

git log --oneline --graph

Isto mostra a sequência de commits de forma compacta e gráfica.

5.5 Guia de Colaboração: Trabalhar em Equipa

Agora iremos focar no poder do GitHub enquanto ferramenta de colaboração. Vamos ver como pode juntar-se a um projeto existente e trabalhar em equipa usando o GitHub Desktop.

5.5.1 Passo 1: Clonar um Repositório

Quando quer contribuir para um projeto que já existe no GitHub, o primeiro passo é clonar o repositório. Clonar significa criar uma cópia local do projeto no seu computador, já ligada ao repositório online.

1. Vá à página do projeto no GitHub.

2. Clique no botão verde “<> Code”.

3. Selecione o separador “HTTPS” e clique no botão “Open with GitHub Desktop”.

Clonar um repositório para o seu computador usando o GitHub Desktop.

4. O seu browser irá pedir permissão para abrir o GitHub Desktop. Permita.

5. O GitHub Desktop irá abrir e perguntar-lhe onde quer guardar o projeto no seu computador (Local Path). Confirme a localização e clique em Clone.

Clonar um repositório no GitHub Desktop.

Agora tem uma cópia completa do projeto no seu computador, incluindo todo o seu histórico.

Comando de Terminal Correspondente

Clonar um repositório no terminal é muito direto. Basta usar o comando git clone seguido do URL que encontra no site do GitHub.

git clone https://github.com/nome-do-dono/nome-do-repo.git
# Exemplo: https://github.com/jdrdionisio/gerador_certificado

Isto cria uma pasta com o nome do repositório e descarrega tudo para lá.

5.5.2 Passo 2: O Ciclo de Colaboração (Fetch, Pull, Push)

O ciclo individual assume que temos uma versão remota e uma versão local onde não haverá alterações remotas que necessitemos de ir buscar. Na analogia de fotografias, que não temos fotografias mais recentes do nosso trabalho de outros colaboradores. No entanto, em equipa, várias pessoas estão a fazer push (tirar fotografias) de alterações para o mesmo repositório. Assim, precisamos de uma forma de nos manter atualizado com o trabalho dos outros e de partilhar o seu.

1. Fetch (Verificar se há novidades): Antes de começar a trabalhar, é boa prática ver se há alterações novas no GitHub. No GitHub Desktop, clique no botão Fetch origin. A aplicação irá contactar o GitHub e verificar se existem novos commits feitos pelos outros colaboradores. Para já não irá alterar os seus ficheiros ainda, apenas informa-o do estado do projeto.

O botão “Fetch origin” verifica se existem alterações no repositório remoto.

2. Pull (Puxar as novidades): Se o Fetch encontrar alterações, o botão transforma-se em Pull origin. Ao clicar nele, o GitHub Desktop irá descarregar essas alterações e aplicá-las (fazer merge ) aos seus ficheiros locais. Isto garante que está a trabalhar na versão mais recente do projeto.

O botão “Pull origin” transfere as alterações no repositório remoto.

3. Modificar, Commitar e Fazer Push: Agora, o seu fluxo de trabalho é o mesmo que já revimos na ciclo de trabalho individual:
   • Fazer alterações locais.
   • Fazer commit das suas alterações com uma mensagem clara.
   • Fazer Push para o GitHub para partilhar o seu trabalho com a equipa.

O ciclo de colaboração é: Pull -> Modificar -> Commitar -> Push.

Execute sempre o Pull antes de começar a trabalhar para evitar conflitos!

Comandos de Terminal Correspondentes

O ciclo de colaboração no terminal é o seguinte: 1. Verificar novidades (Fetch): Descarrega a informação sobre novos commits, mas não os aplica aos seus ficheiros.

git fetch origin

2. Integrar novidades (Pull): O pull é, na verdade, um fetch seguido de um merge. Ele baixa as alterações e tenta fundi-las com o seu trabalho local. Assume que o ramo major se chama main que a predefinição, mas poderá não ser o utilizado no vosso projeto.

git pull origin main

3. Enviar o seu trabalho (Push):

git push origin main

5.6 O Poder dos Branches (Ramos)

Vamos observar duas situaçõe comuns:

A vossa equipa tem de realizar um relatório semanal e nós queremos experimentar uma nova análise sem afetar o projeto principal?

Ou se duas pessoas estiverem a trabalhar em funcionalidades diferentes do projeto ao mesmo tempo que não queremos que afetem os sistemas de produção?

A solução é usar branches (ramos).

Um ramo é uma linha de desenvolvimento paralela. Permite trabalhar isoladamente sem perturbar o ramo principal (que se chama, por defeito, main). Um branch é, na sua essência, apenas um ponteiro leve e móvel para um dos seus commits. O nome de branch por defeito no Git é master.

5.6.1 Porque é que os Branches são Essenciais?

Imagine o ramo main como a versão “oficial” e funcional do seu projeto. Nunca se deve trabalhar diretamente nela se estivermos a falar de um sistema em produção. Em vez disso, para cada nova tarefa/função, cria-se um novo branch devido às seguintes razões:

• Experimentação Segura: Queremos testar um novo modelo de machine learning? Crie um branch experimento-novo-modelo. Se não funcionar, pode simplesmente apagar o branch. O main nunca foi afetado.
• Desenvolvimento Paralelo: Podemos estar a trabalhar na feature-novo-grafico enquanto um colega trabalha no bugfix-leitura-csv. Os vossos trabalhos não interferem um com o outro.
• Código Mais Limpo: O ramo main só recebe trabalho que está completo e revisto. Isto mantém a estabilidade do projeto ao longo do tempo.

5.6.2 O Fluxo de Trabalho com Branches

1. Criar um Novo Branch: Criar um novo ramo a partir do main.
2. Trabalhar no Branch: Fazer commits no seu novo ramo.
3. Abrir um Pull Request: Quando o seu trabalho estiver pronto, abra um “Pull Request” no GitHub. Isto é um pedido para “puxar” as suas alterações do seu ramo para o main. É aqui que a revisão de código acontece.
4. Merge: Depois de aprovado, o seu branch é fundido ( merged ) no main.

Exemplo no GitHub Desktop:

1. Criar um Novo Branch: No GitHub Desktop, clique no menu “Current Branch” e depois no botão New Branch. Dê um nome descritivo ao seu ramo (ex: analise-exploratoria-temp).

   

   Criar um novo branch no GitHub Desktop.

2. Trabalhar no Branch: Todas as alterações e commits que fizer agora serão guardados apenas neste novo ramo.

3. Publicar o Branch: Para que os outros vejam o seu branch (ou para abrir um Pull Request), precisa de o publicar. O GitHub Desktop irá mostrar um botão “Publish branch”.

No final de termos confirmado que as nossas alterações estão estáveis e não afetam o estado funcional do main podemos fazer uma pull request para ser autorizado o merge com o main.

Como fazer pull request e merge com GitHub Desktop.

Comandos de Terminal para Ramos

• Criar um novo branch:

git branch analise-exploratoria-temp

• Mudar para o novo branch:

git checkout analise-exploratoria-temp

• Criar e mudar para o branch num só passo (muito comum):

git checkout -b analise-exploratoria-temp

• Ver todos os branches locais:

git branch

• Enviar um novo branch para o GitHub:

git push -u origin analise-exploratoria-temp

• Apagar um branch localmente (depois de ser merged):

git branch -d analise-exploratoria-temp

5.6.3 Desfazendo Coisas (Reset & Restore)

O que fazer quando comete um erro?

• Descartar alterações num ficheiro que ainda não foram “commitadas”: Se modificou um ficheiro e quer voltar à versão do último commit, no GitHub Desktop pode clicar com o botão direito no ficheiro e escolher “Discard Changes”.
• Reverter um commit inteiro: Se fez um commit e se arrependeu, a forma mais segura é usar a opção “Revert this Commit” no histórico do GitHub Desktop. Isto cria um novo commit que desfaz as alterações do commit anterior, mantendo o histórico intacto.

Como reverte um commit no GitHub Desktop.

Comandos de Terminal para Desfazer Coisas

Estes comandos são poderosos e devem ser usados com cuidado.

• **Descartar alterações na *working directory**: Para um ficheiro chamado analise.R, este comando restaura-o para a versão que está na staging area (ou no último commit, se não estiver na staging area).

git restore analise.R

• Remover um ficheiro da staging area: Se adicionou um ficheiro por engano com git add, pode retirá-lo da staging area com:

    git reset analise.R     
    # ou, com a sintaxe mais moderna:     
    git restore --staged analise.R

• Apagar um ficheiro do Git e do disco:

git rm meu_ficheiro.txt

• Mover/Renomear um ficheiro:

git mv nome_antigo.R nome_novo.R

O conceito mais importante a reter é: crie sempre um novo branch para uma nova tarefa ou funcionalidade. Isto mantém o ramo main limpo e funcional, e é a base de um fluxo de trabalho colaborativo bem-sucedido.

6 Alternativa ao Github Desktop: Integração com RStudio

Em alguns fluxos de trabalho e para algumas pessoas que estão à vontade com o RStudio, a boa notícia é que o RStudio tem uma excelente integração com o Git. Isto permite-lhe realizar a maioria das operações de controlo de versões sem nunca sair do seu ambiente de desenvolvimento.

6.0.1 Configuração Inicial

1. Instalar o Git: O RStudio utiliza a sua instalação de Git do sistema. Se ainda não o fez, instale o Git a partir de git-scm.com.

2. Configurar o RStudio: Vá a Tools > Global Options > Git/SVN. Certifique-se de que o RStudio detetou a sua instalação de Git. Se o campo “Git executable” estiver vazio, procure o ficheiro git.exe (no Windows) ou git (no macOS/Linux).

Configurar o Git no RStudio.

6.0.2 O Painel Git no RStudio

Quando abre um projeto que é um repositório Git no RStudio (seja um que criou ou um que clonou), verá um novo painel chamado “Git” (normalmente no mesmo sítio que “Environment” e “History”).

Devem confirmar que o vosso projeto está configurado para o Github ( Project Setup ).

Definições do Projeto no RStudio.

Este painel lateral pode e deve ser o vosso centro de controlo.

O painel Git no RStudio.

6.0.3 O Fluxo de Trabalho no RStudio

Vamos ver como o ciclo de trabalho Pull -> Modificar -> Commitar -> Push funciona no RStudio.

1. Pull (Receber Alterações): Antes de começar, clicar no botão Pull (seta azul para baixo) no painel Git. Isto irá descarregar e fundir quaisquer alterações do repositório remoto, garantindo que tem a versão mais recente.

2. Modificar Ficheiros: Edite os seus scripts .R ou ficheiros .qmd como faria normalmente no RStudio.

3. Stage (Preparar Alterações): No painel Git, verá uma lista de todos os ficheiros que modificou. Os ícones mostram o estado (M para modificado, A para adicionado, D para apagado). - Para adicionar um ficheiro à área de preparação ( staging area ), marque a caixa “Staged” ao lado do nome do ficheiro. Podem selecionar vários ficheiros com a tecla ctrl. - Pode selecionar vários ficheiros para agrupar as alterações num único commit.

4. Commit (Gravar Alterações): Depois de preparar os ficheiros, clique no botão Commit. - Abrirá uma nova janela. No canto superior direito, escreva a sua mensagem de commit (relembrar indicações-chave de uma mensagem de commit - curta e imperativa). - Clique no botão Commit.

![A janela de commit no RStudio.](images/commit_rstudio.jpg)

5. Push (Enviar Alterações): Após fazer um ou mais commits, o painel Git irá informá-lo de que o seu repositório local está “à frente” do remoto. Clique no botão Push (seta verde para cima) para enviar os seus commits para o GitHub.

6.0.4 Gestão de Ramos no RStudio

O RStudio também torna fácil trabalhar com branches:

• Para ver em que branch está, olhe para o canto superior do painel Git.
• Para criar um novo branch ou mudar de branch, clique no pequeno ícone de branch roxo ( (-< ). Abrirá uma janela onde pode criar um novo branch ou selecionar um existente para fazer checkout.

Gestão de ramos no RStudio.

Trabalhar com Git no RStudio é útil, pois mantém todo o seu fluxo de trabalho, desde a produção de código, análise até ao controlo de versões, num único programa.

6.1 FIM

Chacon, Scott, e Ben Straub. 2014. Pro Git, Everything you need to know about git. Second. Apress. https://git-scm.com/book/en/v2.