Controle de Versão com Git e GitHub

Controle de versão
Git
GitHub
Reprodutibilidade

Um tutorial básico sobre o uso do sistema de controle de versão Git e sobre o GitHub.

Autor
Afiliação

Prof. Dr. Washington S. da Silva

Data de Publicação

7 junho 2024

1 Introdução

Objetivos
  • Este tutorial é destinado aos estudantes do bacharelado em Administração e aos mestrandos do Mestrado Profissional em Administração do IFMG - Campus Formiga.

  • Também é útil para administradores, economistas, contabilistas, auditores e outros profissionais que desejam utilizar ferramentas modernas para criar relatórios e outros produtos de forma reproduzível e auditável.

  • Você não precisa ser programador para aproveitar este material. O tutorial foi elaborado pensando em profissionais de negócios que desejam melhorar seu fluxo de trabalho com documentos, análises e projetos.

O que é Git?
  • Imagine o Git como um “sistema de salvamento inteligente” que registra cada versão dos seus documentos e projetos.

  • Ao contrário do método tradicional de salvar vários arquivos como “Relatório_v1.docx”, “Relatório_v2.docx”, o Git guarda apenas as mudanças, economizando espaço.

  • É como uma “máquina do tempo” para seu trabalho: você pode visualizar ou restaurar qualquer versão anterior quando precisar, sem perder as versões mais recentes.

  • Facilita o trabalho em equipe, permitindo que várias pessoas alterem os mesmos arquivos sem conflitos graves.

Por que usar Git?
  • Evita a confusão de múltiplas versões: Adeus a arquivos como
    Relatorio_Final_v2_Revisado_Corrigido.docx”.

  • Recuperação de trabalho: Se algo der errado, você pode voltar facilmente a uma versão anterior que funcionava.

  • Experimente sem medo: Tente novas abordagens sabendo que pode reverter se não gostar do resultado.

  • Trabalho colaborativo organizado: Múltiplas pessoas podem trabalhar no mesmo projeto sem sobrescrever o trabalho umas das outras.

  • Documentação automática: O histórico de alterações serve como documentação da evolução do seu trabalho.

O que é GitHub?
  • Um serviço online que funciona como uma “nuvem para projetos Git”.

  • Pense no GitHub como um Google Drive ou Dropbox especializado para projetos que usam Git.

  • Além de armazenar seus arquivos, oferece ferramentas para colaboração, revisão e discussão do trabalho.

  • É amplamente usado tanto por desenvolvedores quanto por pesquisadores, analistas e educadores para compartilhar trabalhos.

Por que usar GitHub?
  • Backup seguro: Seus projetos ficam armazenados na nuvem, protegidos contra perda de dados se seu computador falhar ou for perdido.

  • Portfólio profissional: Muitos profissionais usam o GitHub como vitrine de seus trabalhos e habilidades.

  • Colaboração simplificada: Facilita o trabalho em equipe mesmo com pessoas em locais diferentes.

  • Compartilhamento eficiente: Compartilhe seu trabalho com colegas de curso, de trabalho ou com o mundo.

  • Aprendizado constante: Acesse e estude projetos semelhantes ao seu para aprender novas técnicas e abordagens.

2 Instalação e Configuração Básica

2.1 Instando Git no Windows

Instalando o sistema Git no Windows
  1. Baixe o instalador:
  1. Execute o instalador:
  • Clique duplo no arquivo baixado (algo como “Git-2.xx.x-64-bit.exe`”).
  • Aceite as permissões de administrador se solicitado.
  1. Configure o instalador:
  • Mantenha as opções padrão na maioria das telas;

  • Na tela “Adjusting your PATH environment”, escolha a opção recomendada: “Git from the command line and also from 3rd-party software

  • Para as demais opções, as configurações padrão funcionam bem para iniciantes

  1. Conclua a instalação:
  • Clique em “Install” e aguarde a conclusão

  • Ao finalizar, marque a opção “Launch Git Bash” e clique em “Finish” para abrir o Git Bash imediatamente

  1. Verifique a instalação:
  • No Git Bash que abriu, digite: git --version

  • Se aparecer algo como git version 2.xx.x, a instalação foi bem-sucedida!

O que é o Git Bash?
  • O Git Bash é um terminal especial (uma janela de linha de comando) instalado junto com o Git no Windows.

  • Pense nele como uma “janela de comando” onde você digita instruções para o Git.

  • Por que usar o Git Bash em vez do Prompt de Comando do Windows?

    • Oferece comandos adicionais úteis que não existem no prompt padrão do Windows.

    • Funciona de forma mais semelhante ao Git em outros sistemas (Mac, Linux).

    • Possui recursos de autocompletar e visualização colorida que facilitam o us.o

  • Como abrir o Git Bash:

    • Método 1: Pesquise “Git Bash” no menu Iniciar.
    • Método 2: Clique com o botão direito em qualquer pasta e selecione “Git Bash Here” para abrir o terminal já naquela pasta.
  • Não se assuste com a interface de texto!

    • Apesar de parecer complicado no início, você precisará aprender apenas alguns comandos básicos para começar.

2.2 Configuração do Git no seu Computador

Configurando o Git Localmente

Antes de começar a usar o Git, é necessário fazer uma configuração inicial básica. Essa configuração identifica quem está fazendo as alterações e só precisa ser feita uma vez em cada computador.

  1. Configure seu nome de usuário:
  • Abra o Git Bash

  • Digite o comando:

git config --global user.name "nome_sobrenome"
  • Exemplo:
git config --global user.name "maria_silva"
  1. Configure seu email:
  • Use o mesmo email que você usará (ou já usa) para sua conta no GitHub:
git config --global user.email "seu.email@exemplo.com"
  • Exemplo:
git config --global user.email "maria.silva@gmail.com
  1. Verifique suas configurações:
  • Para conferir se tudo está correto:
git config --global --list
  • Isso mostrará todas as suas configurações globais

Estas informações serão usadas para identificar suas contribuições em projetos, então use dados reais, especialmente se for trabalhar em projetos compartilhados.

2.3 Criando Conta no GitHub

Criando uma conta no GitHub

O GitHub é onde você vai armazenar seus projetos Git na nuvem. Criar uma conta é gratuito e simples:

  1. Acesse o site do GitHub:
  1. Preencha o formulário de cadastro:
  • Digite seu email (use o mesmo que configurou no Git local).

  • Crie uma senha segura.

  • Escolha um nome de usuário único:

    • Este será parte do endereço dos seus projetos (github.com/seu-usuario).
    • Recomendação: use algo profissional que você não se importaria de mostrar no currículo.
  1. Verifique seu email:
  • O GitHub enviará um código de verificação para seu email.

  • Insira este código para confirmar sua conta.

  1. Personalize sua experiência (opcional):
  • O GitHub perguntará sobre seu nível de experiência e interesses.

  • Você pode preencher ou pular esta etapa.

  1. Configure a autenticação em dois fatores (recomendado):
  • Para maior segurança, ative a autenticação em dois fatores nas configurações.

  • Isso protege sua conta mesmo se alguém descobrir sua senha.

  1. Crie seu primeiro repositório:
  • Após entrar, clique no botão “+” no canto superior direito.

  • Selecione “New repository” (Novo repositório).

  • Dê um nome ao repositório (por exemplo, “meu-primeiro-projeto”).

  • Clique em “Create repository” (Criar repositório).

Pronto! Sua conta está criada e você já tem seu primeiro repositório no GitHub.

2.4 Configurando o RStudio para usar o Git Bash como Terminal

Configurando o Terminal do RStudio para Git

Como trabalharemos com o sistema Quarto e RStudio, é importante saber como acessar e usar o terminal Git Bash diretamente dentro do RStudio:

  1. Configurando o terminal Git Bash no RStudio:
  • Abra o RStudio

  • Vá para “Tools” > “Global Options” > “Terminal”.

  • No campo “New terminals open with:”, selecione “Git Bash” no menu suspenso.

  • Clique em “Apply” e depois em “OK

  1. Acessando o terminal Git Bash no RStudio:
  • No painel inferior do RStudio, clique na aba “Terminal”.

  • Um novo terminal Git Bash será aberto.

  • Se um terminal já estiver aberto, mas não for o Git Bash, clique no ícone “+” no canto superior direito do painel de terminal e selecione “New Terminal” para abrir um novo terminal Git Bash

  1. Vantagens de usar o Git Bash dentro do RStudio:
  • Mantém seu fluxo de trabalho dentro de um único ambiente.

  • Facilita a navegação entre edição de arquivos e execução de comandos Git.

  • Permite copiar e colar facilmente entre o editor e o terminal.

  • Evita a necessidade de alternar entre aplicativos diferentes.

  1. Verificando se está usando Git Bash:
  • O prompt do Git Bash normalmente mostra o caminho atual e termina com “$”.

  • As cores do texto no terminal são diferentes do terminal padrão do Windows.

  • Você pode digitar echo $SHELL e pressionar Enter - se mostrar algo contendo “bash”, você está no Git Bash.

3 Comandos Essenciais para Começar

Comandos Essenciais

Os quatro comandos básicos que você usará com mais frequência (seu fluxo de trabalho padrão) são:

  • git status: consulta o estado atual dos seus arquivos
  • git add: prepara as mudanças para serem salvas
  • git commit: salva as mudanças no repositório local
  • git push origin main: envia as mudanças para o GitHub

Pense nestes comandos como um processo de 4 passos:

  1. Verificar o que mudou (status).
  2. Adicionar/Selecionar o que você quer salvar (add).
  3. Salvar as mudanças localmente com uma descrição (commit).
  4. Enviar para a nuvem/GitHub (push).

3.1 git status

O que é git status?
  • O comando git status é como tirar uma “foto” do estado atual do seu projeto.

  • O que ele mostra?:

    • Quais arquivos você modificou desde o último salvamento.
    • Quais arquivos são novos e ainda não estão sendo rastreados.
    • Quais mudanças já estão prontas para serem salvas (commit).
  • Quando usar?:

    • Sempre que quiser verificar o que mudou no seu projeto.
    • Antes de fazer um commit para confirmar que está incluindo as mudanças certas.
    • Quando não se lembrar se salvou suas últimas alterações.
  • Exemplo prático: Imagine que você está trabalhando em uma análise de dados e:

    • Modificou seu script principal (analise.R).
    • Adicionou um novo arquivo de dados (dados_2024.csv).
    • Modificou seu relatório (relatorio.qmd).
  • Ao digitar git status, você verá todos esses arquivos listados indicando quais estão prontos para commit (em verde) e quais ainda precisam ser adicionados (em vermelho).

  • É como fazer a pergunta: “O que mudou no meu projeto e o que preciso salvar?”

3.2 git add

O que é git add?
  • O comando git add é como adicionar ou selecionar quais mudanças você quer incluir na próxima “foto” (commit) do seu projeto.

  • Pense nele como a etapa de “seleção” antes de salvar suas mudanças definitivamente.

  • Como funciona na prática?

  • Imagine que você está organizando fotos para um álbum:

    • Você tira várias fotos (faz várias mudanças nos arquivos)
    • Antes de imprimir o álbum, seleciona quais fotos quer incluir (git add)
    • Só depois de selecionar, você finaliza uma página do álbum (git commit)
  • Quando usar? Use git add quando:

    • Terminar de fazer uma alteração que faz sentido ser salva
    • Quiser incluir um novo arquivo ao projeto
    • Antes de fazer um commit

Exemplos de Uso:

  1. Para adicionar apenas um arquivo específico:
git add scripts/analise.R

Esse comando adiciona apenas o arquivo analise.R que está na pasta “scripts”.

Se você estiver trabalhando com análises estatísticas ou financeiras, poderia ser:

git add analise_rentabilidade.R
  1. Para selecionar todos os arquivos de uma pasta:
git add scripts/

Esse comando adiciona todos os arquivos modificados dentro da pasta “scripts”

  1. Para selecionar todos os arquivos modificados do projeto:
git add .

O ponto “.” significa “todos os arquivos” - use com cuidado!

Dica para iniciantes:

  • Comece usando o comando completo para cada arquivo até se familiarizar com o processo.

  • Depois, quando estiver mais confiante, você pode usar o git add . para adicionar vários arquivos de uma vez.

3.3 git commit

O que é git commit?
  • O git commit é o momento de “salvar oficialmente” as mudanças que você selecionou com o git add.

  • É como tirar uma foto do estado atual do seu projeto e adicionar uma legenda descrevendo o que mudou.

  • Cada commit cria um ponto na linha do tempo do seu projeto ao qual você pode voltar se precisar.

Como usar:

git commit -m "mensagem descrevendo o que você fez"

A parte -m "mensagem" é onde você explica brevemente o que mudou.

Exemplos de boas mensagens de commit:

git commit -m "adiciona análise inicial dos dados de vendas"
git commit -m "corrige fórmulas na seção de métodos"
git commit -m "finaliza capítulo 3 da dissertação"

Quando fazer um commit?

Pense em cada commit como um “marco” no seu trabalho:

  • Após completar uma tarefa específica: “Terminei de analisar os dados de janeiro” → commit

  • Após resolver um problema: “Corrigi o erro nas referências” → commit

  • Antes de fazer uma mudança grande ou arriscada: “Vou reorganizar toda a estrutura do documento” → commit primeiro!

Analogia: Se seu trabalho fosse uma viagem, cada commit seria como fincar uma bandeira no caminho dizendo “cheguei até aqui com segurança”. Se você se perder depois, pode sempre voltar a este ponto.

Recomendação para iniciantes: Faça commits frequentes! É melhor ter muitos pequenos commits do que poucos commits gigantes.

3.4 git push

O que é git push?
  • O comando git push envia as mudanças que você salvou localmente (com commit) para o GitHub.

  • É como sincronizar seu trabalho local com a “nuvem”, tornando-o disponível para outras pessoas ou em outros computadores.

Como funciona na prática:

Imagine que você:

  1. Fez várias alterações no seu computador
  2. Adicionou essas alterações (git add)
  3. Salvou-as localmente (git commit)

Neste ponto, as mudanças estão apenas no seu computador! Para enviar ao GitHub:

git push origin main

O que significa “origin main”?

  • origin é o nome padrão que o Git dá ao seu repositório remoto no GitHub (como um “apelido” para o endereço completo)

  • main é o nome do ramo principal do seu projeto (anteriormente chamado de “master” em projetos mais antigos)

Quando fazer um push?

  • Ao terminar uma sessão de trabalho
  • Quando quiser compartilhar seu progresso com colegas
  • Como backup de segurança do seu trabalho
  • Antes de mudar para outro computador

Analogia: Se os commits são como salvar seu jogo em um cartão de memória, o push é como fazer um backup desse cartão na nuvem. Se seu computador quebrar, você não perde o progresso.

Dica: Para ver se seu push funcionou, acesse seu repositório no GitHub pelo navegador - você deverá ver todas as mudanças que acabou de enviar.

3.5 Uso do Git via Terminal no RStudio

Usando Git via Terminal no RStudio

Todos os comandos Git que aprendemos serão executados através do terminal Git Bash dentro do RStudio:

  1. Abra o terminal no RStudio:
  • Clique na aba “Terminal” no painel inferior do RStudio.

  • Certifique-se de que está usando o Git Bash (o prompt deve terminar com “$”).

  1. Navegue até a pasta do projeto:
  • Se você estiver trabalhando em um Projeto RStudio, o terminal já estará aberto na pasta correta.

  • Caso contrário, use o comando cd para navegar até a pasta do seu projeto.

  1. Execute os comandos Git normalmente:
# Verificar o estado atual
git status

# Adicionar arquivos para o próximo commit
git add nome-do-arquivo.qmd

# Fazer um commit com mensagem
git commit -m "Adiciona análise descritiva"

# Enviar para o GitHub
git push origin main

Por que usar o terminal em vez da interface Git do RStudio?

  • Mais rápido e responsivo.

  • Menos sobrecarga visual, ajudando a focar no que realmente importa.

  • As mesmas habilidades são transferíveis para qualquer ambiente, não apenas RStudio.

  • Mensagens de erro e avisos são exibidos com mais clareza.

  • Fornece mais controle sobre o processo Git.

Dica para iniciantes:

Mantenha uma “cola” dos comandos Git mais comuns por perto até se familiarizar com eles. Com o tempo, você os memorizará naturalmente através do uso frequente.

4 Comandos Úteis para o Dia a Dia (Opcional)

Após se sentir familiarizado e confortável com os 4 comandos essenciais explicandos na Seção 3, vale a pena conhecer e testar outros comandos úteis para o dia a dia, como o comando git diff.

4.1 git diff

O que é git diff?
  • O comando git diff mostra as alterações específicas que foram feitas nos arquivos, mas que ainda não foram preparadas para commit (não passaram pelo git add).

  • É como um “modo de revisão” que destaca exatamente o que foi adicionado (em verde) e o que foi removido (em vermelho).

  • Quando usar?:

    • Antes de adicionar arquivos com git add, para revisar exatamente o que foi alterado.
    • Para verificar detalhes das modificações que o git status apenas lista.
    • Quando você não se lembra exatamente o que mudou em um arquivo específico.
  • Exemplos de Uso:

  1. Para ver todas as mudanças não preparadas:
git diff
  1. Para ver as mudanças em um arquivo específico:
git diff relatorio.qmd
  1. Para ver as mudanças que já foram preparadas com git add (e irão para o próximo commit):
git diff --staged
  • Analogia: Se o git status é como uma lista de compras que mostra quais itens você precisa, o git diff é como abrir cada item para inspecionar seu conteúdo antes de colocá-lo no carrinho.

  • Como interpretar o resultado:

    • Linhas que começam com + mostram conteúdo adicionado
    • Linhas que começam com - mostram conteúdo removido
    • O contexto (linhas não alteradas) aparece sem símbolos especiais
  • Dica para iniciantes:

Use o git diff antes de cada git add para ter certeza de que está adicionando apenas as alterações desejadas, especialmente quando trabalha com documentos importantes como relatórios financeiros, análises de dados ou capítulos de dissertação.

5 Workflow para Trabalhar Colaborativamente

Objetivo desta seção
  • Apresentar um passo a passo prático para orientandos de mestrado colaborarem com seus orientadores usando Git e GitHub.

  • Estabelecer um fluxo de trabalho claro que minimize conflitos e maximize a produtividade.

  • Servir como guia inicial que pode ser adaptado para outros tipos de colaboração acadêmica.

Visão Geral do Workflow Colaborativo

O fluxo de trabalho a seguir foi desenhado especificamente para a dinâmica entre orientando e orientador, onde ambos contribuem para documentos como dissertações, artigos e análises de dados.

  1. Configuração inicial (feita apenas uma vez).

  2. Ciclo de desenvolvimento (repetido diariamente/semanalmente).

  3. Incorporação de feedback (quando o orientador fizer sugestões).

Fluxo básico:

  1. Orientando baixa/puxa mudanças do repositório no GitHub (pull)
  2. Orientando trabalha nos arquivos
  3. Orientando envia mudanças (commit + push)
  4. Orientador baixa/puxa mudanças (pull)
  5. Orientador revisa e faz sugestões
  6. Orientador envia feedback (commit + push)
  7. Orientando baixa/puxa o feedback (voltando ao passo 1)

5.1 Configuração Inicial para o Exame de Qualificacão do Mestrado

Configuração Inicial - Orientando

Esta etapa será realizada apenas uma vez, no início do trabalho com seu orientador:

  1. Utilizando o Templote Quarto para o Exame de Qualificação:
  • Acesse o repositório do template: Template para o Exame de Qualificaçao do Mestrado

  • Clique no botão “Use this template” no topo da página

  • Clique em “Create a new repository

  • Na próxima página, escreva um nome para o seu repositório, por exemplo,
    repositorio_exame_qualificacao, no campo abaiso de “Repository name”.

  • Revise e estando tudo ok, clique no botão verde “Create repository”.

  • Pronto! você acabou de criar um repositório disponível na sua conta do GitHub contendo o template Quarto para o exame de qualificação do mestrado.

  1. Adicione seu orientador como colaborador:
  • Dentro do seu repositório do template, clique na aba “Settings” (localizada na parte superior da página).

  • No menu lateral esquerdo, clique em “Collaborators” (pode estar dentro da seção “Access”).

  • Clique no botão “Add people”.

  • Digite o email cadastrado ou nome de usuário do seu orientador no GitHub.

  • Selecione o perfil do seu orientador e escolha o nível de permissão (recomendado: “Write” ou “Maintain”).

  • Clique em “Add [nome do colaborador]”.

  • O GitHub enviará um convite por email ao seu orientador; e le precisará aceitar o convite para ter acesso.

  1. Clone o repositório para seu computador usando o RStudio:
  • Abra o RStudio

  • Clique em Project -> New Project -> Version Control -> Git (clone a project from a github repository).

  • Usando seu navegoar, dentro do seu repositório no GitHub, clique no botão verde “Code”.

  • Verifique se a opção “HTTPS” está selecionada (em vez de SSH ou GitHub CLI).

  • Copie a URL mostrada (que terá o formato https://github.com/seu-usuario/nome-repositorio.git)

  • No RStudio, cole a URL do repositório no campo abaixo de “Repository URL

  • Defina um nome para o repositório local, pode ser o mesmo nome do repositório no GitHub: repositorio_exame_qualificacao

  • Antes de cliar no botão “Create” verifique se o endereço exibido abaixo de “Create projet as subdirectory of:” está apontando para a pasta do seu computador na qual deseja salvar o repositório localmente.

  • Caso necessário, clique em “browse” e selecione a pasta onde deseja salvar o repositório no seu computador.

  • Clique em “Create

  1. Verificação final:
  • Confirme que o repositório foi clonado corretamente observando se a pasta no seu computador contém os arquivos do repositório do template quarto

  • Digite git status para verificar o estado atual do seu repositório local

5.2 Ciclo de Desenvolvimento

Ciclo Diário/Semanal de Trabalho - Orientando

(usando Terminal no RStudio)

Este é o ciclo que você repetirá regularmente enquanto trabalha em seu projeto:

  1. Comece o dia de trabalho atualizando seu repositório local:
  • Abra seu projeto no RStudio

  • Clique na aba “Terminal” no painel inferior

  • Execute o comando:

git pull origin main

Este comando baixa qualquer mudança que seu orientador possa ter feito.

  1. Trabalhe em seus arquivos normalmente no RStudio:
  • Edite seus arquivos .qmd
  • Execute análises no R
  • Gere tabelas e visualizações
  • Renderize documentos Quarto

Trabalhe como você normalmente faria no RStudio.

  1. Salve seu progresso usando o terminal Git Bash no RStudio:

A cada conquista significativa ou no final do dia, sem sair do RStudio, use o terminal para:

# Verifique o que mudou
git status

# Veja as alterações específicas (opcional)
git diff arquivo-modificado.qmd

# Adicione os arquivos modificados (você pode especificar arquivos individuais)
git add .

# Salve as mudanças localmente com uma mensagem descritiva
git commit -m "Adiciona análise descritiva no capítulo 3"

# Envie para o GitHub
git push origin main

Benefícios deste fluxo de trabalho:

  • Mantém tudo em um único ambiente (RStudio)
  • Usa comandos Git de forma direta e transparente
  • Evita problemas de desempenho da interface gráfica
  • Facilita a compreensão do que está realmente acontecendo

Lembre-se: Fazer commits pequenos e frequentes com mensagens descritivas claras ajuda tanto você quanto seu orientador a acompanhar o progresso do trabalho.

5.3 Incorporação de Feedback

Quando seu Orientador Fornecer Feedback - Orientando

Este processo ocorre depois que seu orientador revisar seu trabalho e fizer alterações:

  1. Obtenha as mudanças feitas pelo orientador:

Em um terminal Git Bash dentro do RStudio execute:

git pull origin main

Isso baixa as alterações, comentários ou correções feitas pelo orientador.

  1. Revise as mudanças:

Novamente, Em um terminal Git Bash dentro do RStudio execute:

# Para ver quais arquivos foram modificados pelo orientador
git log

# Para ver as mudanças específicas em um arquivo
git diff HEAD~1 HEAD -- caminho/do/arquivo

Este comando mostra o que mudou entre a versão atual e a anterior.

  1. Trabalhe com as sugestões:
  • Implemente as correções sugeridas.

  • Responda a questionamentos (pode ser no próprio documento ou em um comentário no GitHub).

  • Complemente seções conforme solicitado.

  1. Continue o ciclo normal:

Volte ao passo 2 (Ciclo de Desenvolvimento) e continue seu trabalho.

5.4 Lidando com Conflitos

Resolvendo Conflitos via Terminal no RStudio

Quando ocorrem conflitos durante um pull, você pode resolvê-los diretamente no RStudio:

  1. Identificando conflitos:

Ao executar git pull no terminal, você verá uma mensagem como:

CONFLICT (content): Merge conflict in nome-do-arquivo.qmd
Automatic merge failed; fix conflicts and then commit the result.
  1. Abrindo e editando o arquivo com conflito:
  • No RStudio, abra o arquivo com conflito no editor
  • RStudio mostrará as marcações de conflito com formatação visual:
<<<<<<< HEAD
Seu texto (versão local)
=======
Texto do orientador (versão do GitHub)
>>>>>>> abcd1234
  1. Resolvendo o conflito:
  • Edite manualmente o arquivo, removendo as marcações de conflito
  • Mantenha o texto que faz mais sentido (seu texto, o texto do orientador, ou uma combinação de ambos)
  • Remova completamente as linhas com <<<<<<< HEAD, ======= e >>>>>>> abcd1234
  • Salve o arquivo
  1. Concluindo a resolução via terminal:

Após resolver todos os conflitos no editor, volte ao terminal no RStudio:

# Verifique se todos os conflitos foram resolvidos
git status

# Adicione o arquivo resolvido
git add nome-do-arquivo.qmd

# Faça um commit da resolução
git commit -m "Resolve conflito no arquivo nome-do-arquivo.qmd"

# Envie para o GitHub
git push origin main

Dica: Comunique-se com seu orientador quando encontrar conflitos. Às vezes, uma conversa rápida pode esclarecer qual versão deve ser mantida.

5.5 Trabalhando com Issues do GitHub

Usando Issues para Organizar Tarefas

O GitHub possui uma ferramenta chamada “Issues” que é excelente para:

  • Listar tarefas pendentes
  • Registrar problemas a serem resolvidos
  • Documentar discussões entre orientando e orientador

Como usar:

  1. Crie uma issue:
  • No GitHub, acesse a aba “Issues” do repositório.
  • Clique em “New issue”.
  • Dê um título descritivo e explique a tarefa/problema.
  • Use marcadores como listas, negrito e itálico para organizar.
  • Adicione etiquetas (labels) como “revisão”, “urgent”, “discussão”.
  1. Acompanhe o progresso:
  • Comente nas issues para atualizar o progresso.
  • Referencie commits relacionados usando “#” (exemplo: “Resolve #4”).
  • Feche a issue quando a tarefa estiver concluída.
  1. Referencie issues nos commits:
git commit -m "Adiciona análise de correlação solicitada na issue #5"

Isso cria uma referência cruzada que facilita acompanhar o histórico de mudanças e discussões.

5.6 Aplicando este Workflow a Outros Cenários

Adaptando para Outras Colaborações

Este mesmo fluxo de trabalho pode ser facilmente adaptado para colaborar com:

  • Colegas de classe em projetos em grupo.
  • Outros pesquisadores em artigos científicos.
  • Equipes de trabalho em relatórios ou análises.
  • Projetos de extensão ou iniciação científica.

A mesma lógica se aplica:

  1. Configuração inicial (uma vez).
  2. Ciclo frequente de atualizações.
  3. Incorporação de feedback dos colaboradores.

A diferença principal em outros cenários pode ser a necessidade de usar “branches” (ramificações) para trabalhos mais complexos com múltiplos colaboradores, um tópico que pode ser explorado quando você já estiver confortável com este fluxo básico.

5.7 Resumo do Workflow

Resumindo

O ciclo de trabalho com seu orientador segue este padrão:

  1. Comece o dia puxando alterações: git pull origin main

  2. Trabalhe nos arquivos normalmente

  3. Verifique mudanças: git status e git diff

  4. Salve seu progresso:

    git add .
    git commit -m "Mensagem descritiva"
    git push origin main
  5. Repita diariamente ou quando concluir uma parte significativa

Lembre-se: a comunicação clara com seu orientador sobre qual parte cada um está trabalhando pode evitar conflitos e retrabalho.

5.8 Dicas para usar o Terminal Git Bash no RStudio

Dicas para usar o Terminal Git Bash no RStudio

Para tornar seu trabalho com Git mais eficiente usando o terminal no RStudio:

  1. Atalhos úteis no terminal Git Bash:
  • Pressione a tecla “seta para cima” para acessar comandos anteriores
  • Use Tab para autocompletar nomes de arquivos e comandos
  • Ctrl+C cancela um comando em execução
  • Ctrl+L limpa a tela do terminal (ou digite clear)
  1. Verificando rapidamente as mudanças:
# Ver mudanças em um arquivo específico
git diff caminho/para/arquivo.qmd

# Ver apenas os nomes dos arquivos modificados
git status -s
  1. Adicionando arquivos seletivamente:
# Adicionar arquivos interativamente (pergunta arquivo por arquivo)
git add -i

# Adicionar apenas partes específicas de um arquivo
git add -p
  1. Revertendo mudanças quando necessário:
# Descartar mudanças em um arquivo específico (cuidado!)
git checkout -- nome-do-arquivo.qmd

# Desfazer o último commit (mantendo as mudanças)
git reset --soft HEAD~1
  1. Visualizando o histórico:
# Ver histórico resumido
git log --oneline

# Ver histórico com detalhes das mudanças
git log -p

# Ver histórico de um arquivo específico
git log -p nome-do-arquivo.qmd
  1. Mantendo o terminal aberto:
  • Você pode manter o terminal Git Bash aberto o tempo todo enquanto trabalha.

  • Para abrir um novo terminal sem fechar o atual, clique no ícone “+” no painel do terminal.

  • Use diferentes terminais para diferentes tarefas (um para Git, outro para R, etc.).

  1. Salvando comandos frequentes em um arquivo de texto:
  • Crie um arquivo de texto no seu projeto chamado “git-comandos.txt”.

  • Guarde ali os comandos que você usa com frequência para copiar e colar.

  • Adicione comentários úteis ao lado de cada comando.

6 Recuperando Versões Anteriores de Arquivos

Recuperando Versões Anteriores

Uma das principais vantagens do Git é a possibilidade de voltar no tempo e recuperar versões anteriores dos seus arquivos. Esta funcionalidade é especialmente útil quando:

  • Você fez alterações que não funcionaram como esperado.
  • Precisa consultar como o texto estava redigido anteriormente.
  • Deseja recuperar conteúdo que foi removido acidentalmente.

Vamos ver como fazer isso através do terminal Git Bash no RStudio:

Visualizando o Histórico de um Arquivo

Antes de recuperar uma versão anterior, você precisa identificar quando (em qual commit) o arquivo estava no estado que você deseja recuperar:

  1. Veja o histórico de commits do arquivo:
git log --follow arquivo.qmd

O parâmetro --follow é útil para ver o histórico mesmo se o arquivo foi renomeado.

  1. Visualização mais compacta:
git log --follow --oneline arquivo.qmd

Isso mostrará cada commit em uma única linha, com seu ID (hash) e mensagem.

Exemplo de resultado:

a7f3de6 Atualiza análise estatística da seção 3
b9e8d12 Corrige tabelas e adiciona conclusões
f7d2e09 Primeira versão do capítulo metodologia
  1. Anote o ID (hash) do commit que contém a versão que você deseja recuperar. No exemplo acima, poderia ser f7d2e09 se você quisesse voltar à primeira versão.
Visualizando o Conteúdo de uma Versão Antiga

Para verificar o conteúdo antes de recuperá-lo:

git show hash:arquivo.qmd

Substitua hash pelo ID do commit e arquivo.qmd pelo nome do seu arquivo.

Exemplo:

git show f7d2e09:metodologia.qmd

Isso mostrará o conteúdo do arquivo metodologia.qmd como estava no commit f7d2e09, sem alterar seu arquivo atual.

Recuperando uma Versão Antiga

Há duas maneiras principais de recuperar uma versão antiga de um arquivo:

Método 1: Sobrescrever o arquivo atual

Este método substitui completamente seu arquivo atual pela versão antiga:

git checkout hash -- arquivo.qmd

Exemplo:

git checkout f7d2e09 -- metodologia.qmd

O que acontece?

  • Seu arquivo atual é substituído pela versão antiga
  • A mudança aparece como uma modificação não commitada
  • Você ainda precisa adicionar e commitar esta mudança

Depois de executar o comando acima, você precisará:

git add metodologia.qmd
git commit -m "Restaura versão anterior da metodologia"

Método 2: Criar uma cópia da versão antiga

Se você quiser manter seu arquivo atual e apenas examinar a versão antiga:

git show hash:arquivo.qmd > arquivo_antigo.qmd

Exemplo:

git show f7d2e09:metodologia.qmd > metodologia_antiga.qmd

Isso criará um novo arquivo chamado metodologia_antiga.qmd com o conteúdo da versão antiga, sem afetar seu arquivo atual.

Dicas e Observações
  • Identifique o commit correto: Use git log com cuidado para encontrar exatamente a versão que deseja.

  • Salve seu trabalho atual: Faça commit de suas mudanças atuais antes de recuperar versões antigas.

  • Lembre-se do formato do comando: O formato git checkout hash -- arquivo é importante; não esqueça os dois traços antes do nome do arquivo.

  • Recuperação parcial: Se quiser recuperar apenas partes específicas de uma versão antiga, use a segunda abordagem e depois copie manualmente as partes relevantes.

Esta funcionalidade de “máquina do tempo” é uma das maiores vantagens do Git em comparação com o método tradicional de salvar múltiplas cópias de arquivos com nomes diferentes.

7 Glossário de Termos

B

Branch: Ramificação independente do código que permite trabalhar em funcionalidades ou correções sem afetar a linha principal de desenvolvimento.

C

Clone: Cópia completa de um repositório, incluindo todos os arquivos, histórico e branches, para o computador local.

Commit: “Fotografia” do estado do projeto em um determinado momento, com uma mensagem descritiva das alterações realizadas.

Conflito: Situação onde o Git não consegue mesclar automaticamente alterações de diferentes fontes porque ambas modificaram a mesma parte de um arquivo.

F

Fork: Cópia pessoal de um repositório de outra pessoa no GitHub, permitindo experimentar mudanças sem afetar o projeto original.

G

Git: Sistema de controle de versão distribuído que registra alterações em arquivos ao longo do tempo.

Git Bash: Terminal especial instalado com o Git no Windows que permite executar comandos Git e outros comandos Unix.

GitHub: Plataforma online que hospeda repositórios Git e oferece ferramentas adicionais para colaboração e desenvolvimento de projetos.

H

Hash: Identificador único (como f7d2e09) gerado para cada commit, permitindo referenciar versões específicas dos arquivos.

I

Issue: Funcionalidade do GitHub para rastrear tarefas, melhorias, bugs e outras questões relacionadas a um projeto.

M

Main: Branch principal de um repositório Git (anteriormente chamado de “master”).

Merge: Processo de unir alterações de diferentes branches ou commits.

O

Origin: Nome padrão dado ao repositório remoto (normalmente no GitHub) a partir do qual um repositório local foi clonado.

P

Pull: Ação de baixar as alterações do repositório remoto para o repositório local, atualizando-o.

Push: Ação de enviar commits do repositório local para o repositório remoto (GitHub).

R

Repositório: Coleção de arquivos e pastas de um projeto, junto com o histórico completo de alterações.

Repositório Local: Versão do repositório armazenada no seu computador.

Repositório Remoto: Versão do repositório armazenada em um servidor (como o GitHub).

S

Stage/Staging Area: Área intermediária onde as alterações são adicionadas (via git add) antes de serem definitivamente salvas em um commit.

T

Terminal: Interface de linha de comando onde os comandos Git são executados.

W

Working Directory: Diretório local onde os arquivos do projeto estão sendo editados ativamente.

8 Referências

BLISCHAK, J. D.; DAVENPORT, E. R.; WILSON, G. A Quick Introduction to Version Control with Git and GitHub. PLoS Computational Biology, v. 12, n. 1, p. e1004668, 2016.
CHACON, S.; STRAUB, B. Pro Git. 2. ed. [s.l.] Apress, 2014.
OLIVEIRA, D. Git4Noobs: Tutorial de Git para iniciantesGitHub Repository, 2020. Disponível em: <https://github.com/DanielHe4rt/git4noobs>