46 Controle de versão e colaboração com Git e Github

Este capítulo apresenta uma visão geral do uso do Git para programar em colaboração com outras pessoas. Tutoriais mais completos podem ser encontrados abaixo na seção Recursos.

46.1 O que é o Git?

Git é um software de controle de versões que permite rastrear alterações em uma pasta. Pode ser usado como a opção de “controle de alterações” no Word, LibreOffice ou Google docs, mas para todos os tipos de arquivos. É uma das opções mais poderosas e mais usadas para controle de versões.

Por que eu nunca ouvi falar disso? Enquanto pessoas com formação em programação aprendem rotineiramente a usar softwares de controle de versões (Git, Mercurial, Subversion ou outros), poucos de nós das disciplinas quantitativas aprendem essas habilidades. Consequentemente, a maioria dos epidemiologistas nunca ouviu falar dele durante seus estudos, e tem que aprender repentinamente.

Espera, já ouvi falar do Github, é a mesma coisa? - Não exatamente, mas costumamos usá-los juntos. E nós mostraremos como fazer. Resumidamente:

Git é o sistema de controle de versão, um software. Você pode usá-lo localmente em seu computador ou para sincronizar uma pasta com um site hospedeiro. Por padrão, usa-se um terminal para fornecer instruções Git na linha de comando.
Você pode usar um cliente / uma interface Git para evitar a linha de comando e executar as mesmas ações (pelo menos para as simples e supercomuns).
Se você deseja armazenar sua pasta em um site hospedeiro para colaborar com outras pessoas, você pode criar uma conta no Github, Gitlab, Bitbucket ou outros.

Portanto, você pode usar o cliente ou a interface Github Desktop, que usa Git em segundo plano para gerenciar seus arquivos, tanto localmente em seu computador quanto remotamente em um servidor Github.

46.2 Por que usar o combo Git e Github?

Usar o Git facilita:

Arquivar versões documentadas com mudanças adicionais para que você possa recuperar facilmente qualquer versão anterior;
Ter ramos ( do inglês branches) paralelos, ou seja, desenvolver / “trabalhar” diferentes versões com formas estruturadas de integrar as mudanças após a revisão.

Isso pode ser feito localmente em seu computador, mesmo se você não colaborar com outras pessoas. Você já:

lamentou ter excluído uma seção do código, para perceber apenas dois meses depois que você realmente precisava dela?
voltou em um projeto que estava parado e tentou lembrar se você fez aquela modificação complicada em um dos modelos?
teve um arquivo modelo_1.R , outro arquivo modelo_1_teste.R e ainda um outro arquivo modelo_1_nao_funciona.R para testar diferentes soluções?
teve um arquivo relatorio.Rmd, um arquivo relatorio_completo.Rmd , um arquivo relatorio_verdadeiro_final.Rmd, um arquivo relatorio_final_20210304.Rmd, um arquivo relatorio_final_20210402.Rmd e amaldiçoou suas habilidades de backup?

Git vai ajudar com tudo isso, e vale a pena aprender só por isso.

No entanto, ele se torna ainda mais poderoso quando usado com um repositório online para oferecer suporte a projetos colaborativos, como o Github. Isso facilita: - Colaboração: outras pessoas podem revisar, comentar e aceitar/recusar as alterações;

Compartilhar seu código, dados e resultados e solicitar feedback em público (ou em particular, com sua equipe).

E evita:

“Opa, esqueci de enviar a última versão e agora você precisa refazer dois dias de trabalho neste novo arquivo”;
Patrícia, Ruanna e Nathalie trabalharam ao mesmo tempo em um script e precisam mesclar manualmente suas alterações;
Duas pessoas tentam modificar o mesmo arquivo no Dropbox e no Sharepoint e isso cria um erro de sincronização.

Isso parece complicado, não sou um programador

Pode ser. Exemplos de usos avançados podem ser bastante assustadores. No entanto, assim como no R, ou mesmo no Excel, você não precisa se tornar um especialista para aproveitar os benefícios da ferramenta. Aprender um pequeno número de funções e noções permite rastrear suas alterações, sincronizar seus arquivos em um repositório online e colaborar com seus colegas em um período de tempo muito curto.

Devido à curva de aprendizado, o contexto de emergência pode não ser o melhor momento para aprender essas ferramentas. Mas o aprendizado pode ser alcançado por etapas. Depois de adquirir algumas noções, seu fluxo de trabalho pode ser bastante eficiente e rápido.

Um bom momento para adquirir confiança no uso do Git, na verdade, é quando você não está trabalhando em um projeto que precise dele, quando trabalhar em colaboração não é uma necessidade.

46.3 Configuração

Instale o Git

Git é o mecanismo por trás dos bastidores do seu computador, que rastreia alterações, ramos (versões), mesclagens e reversões. Você deve primeiro instalar o Git em https://git-scm.com/downloads.

Instale uma interface (opcional, mas recomendado)

Git tem sua própria linguagem de comandos, que pode ser digitada em um terminal de linha de comando. No entanto, existem muitos clientes / interfaces e, não sendo um desenvolvedor, você raramente precisará interagir diretamente com o Git na sua rotina. As interfaces geralmente fornecem boas ferramentas de visualização para modificações ou ramificações de arquivos.

Existem muitas opções, em todos os sistemas operacionais, desde iniciantes até os mais complexos. Boas opções para iniciantes incluem o painel RStudio Git e Github Desktop, que mostraremos neste capítulo. Opções intermediárias (mais poderosas, mas mais complexas) incluem Source Tree, Gitkracken, Smart Git e outras.

Explicação rápida sobre Clientes Git.

Observação: como todas as interfaces usam o Git internamente, você pode tentar várias delas, alternar de uma para outra em um determinado projeto, usar o console pontualmente para uma ação que sua interface não suporta ou até mesmo realizar algumas ações online no Github.

Conforme observado abaixo, você pode ocasionalmente ter que escrever comandos Git em um terminal, como o painel RStudio (uma aba do Console R) ou o terminal Git Bash.

Conta Github

Inscreva-se para uma conta gratuita em github.com.

Pode ser solicitado que você configure a autenticação de dois fatores com um aplicativo em seu telefone. Leia mais em nos documentos de ajuda do Github.

Se você usa o Github Desktop, pode inserir suas credenciais do Gitub após a instalação seguindo estas etapas. Se você não fizer isso agora, as credenciais serão solicitadas mais tarde, quando você tentar clonar um projeto do Github.

46.4 Vocabulário, conceitos e funções básicas

Assim como ao aprender R, há um pouco de vocabulário que você precisará lembrar para entender o Git. Aqui estão os princípios básicos para você começar e um tutorial interativo. Nas próximas seções, mostraremos como usar interfaces, mas é bom ter o vocabulário do Git e os conceitos em mente, para construir seu modelo mental. Você precisará deles ao usar interfaces de qualquer maneira.

Repositório

Um repositório Git (“repo”) é uma pasta que contém todas as subpastas e arquivos do seu projeto (dados, códigos, imagens etc.), além dos seus históricos de revisão. Quando você começar a rastrear as alterações no repositório com o Git, ele criará uma pasta oculta que contém todas as informações de rastreamento. Um repositório Git típico é a pasta Projeto R (consulte a página do manual em Projetos R).

Mostraremos como criar (inicializar) um repositório Git a partir do Github, Github Desktop ou Rstudio nas próximas seções.

Commits ()

Um commit é um snapshot do projeto, ou seja, uma foto instantânea de um determinado momento. Ao fazer uma alteração no projeto, você fará um novo commit para rastrear as alterações (o delta) feitas em seus arquivos. Por exemplo, talvez você tenha editado algumas linhas de código e atualizado um conjunto de dados. Depois que suas alterações forem salvas, você pode agrupar essas alterações em um “commit”.

Cada commit possui um ID exclusivo (um hash). Para fins de controle de versão, você pode recuperar seu projeto no tempo com base em commits, então é melhor mantê-los relativamente pequenos e coerentes. Você também anexará uma breve descrição das mudanças, chamada de “mensagem de confirmação”.

Mudanças graduais? Preparar mudanças é adicioná-las à área de teste, em preparação para o próximo commit. A ideia é que você possa decidir com precisão quais alterações incluir em um determinado commit. Por exemplo, se você trabalhou na especificação do modelo em um script e, posteriormente, trabalhou em uma figura em outro script, faria sentido ter dois commits diferentes (seria mais fácil no caso de você querer reverter as mudanças na figura, mas não o modelo).

Branches (Ramos)

Um branch representa uma linha independente de mudanças em seu repo, uma versão paralela e alternativa de seus arquivos de projeto.

Branches são úteis para testar mudanças antes de serem incorporadas ao branch principal, que geralmente é a versão primária / final / “ativa” do seu projeto. Quando você terminar de experimentar em um branch, você pode trazer as alterações para o seu branch principal, mesclando, ou excluí-lo, se as alterações não foram tão bem-sucedidas.

Observação: você não precisa colaborar com outras pessoas para usar branches, nem precisa ter um repositório online remoto.

Repositórios locais e remotos

Clonar é criar uma cópia de um repositório Git em outro lugar.

Por exemplo, você pode clonar um repositório online do Github localmente em seu computador, ou começar com um repositório local e cloná-lo online para Github.

Quando você clona um repositório, os arquivos do projeto ficam em dois lugares:

no repositório LOCAL, em seu computador físico. É aqui que você faz as mudanças reais nos arquivos / códigos.
no repositório online REMOTO: versões dos seus arquivos de projeto no repositório Github (ou em qualquer outro site hospedeiro).

Para sincronizar esses repositórios, usaremos mais funções. Na verdade, ao contrário do Sharepoint, Dropbox ou outro software de sincronização, o Git não atualiza automaticamente seu repositório local baseado naquele que está online ou vice-versa. Você pode escolher quando e como sincronizar.

git fetch baixa as novas mudanças do repositório remoto, mas não muda seu repositório local. Pense nela como uma verificação de estado do repositório remoto.
git pull baixa as novas mudanças dos repositórios remotos e atualiza seu repositório local.
Quando você tiver feito um ou vários commits localmente, você pode usar git push para atualizar os commits no repositório remoto. Isso envia suas alterações no Github para que outras pessoas possam vê-las e acessá-las, se quiserem.

46.5 Começar: crie um novo repositório

Existem muitas maneiras de criar novos repositórios. Você pode fazer isso no console, no Github, em uma interface.

Duas abordagens gerais são:

Criar um novo Projeto R a partir de um repositório Github novo ou existente (sugerido para iniciantes);
Criar um repositório Github para um projeto R existente.

Arquivos iniciais

Ao criar um novo repositório, você pode opcionalmente criar todos os arquivos abaixo ou pode adicioná-los ao seu repositório em um estágio posterior. Eles normalmente ficam na pasta “raiz” do repositório.

-Um arquivo README é um arquivo que alguém pode ler para entender por que seu projeto existe e o que mais precisar saber para usá-lo. Ele estará vazio no início, mas você deve preenchê-lo mais tarde.

Um arquivo .gitignore é um arquivo de texto em que cada linha contém pastas ou arquivos que o Git deve ignorar (não rastrear alterações). Leia mais sobre ele e veja exemplos aqui.
Você pode escolher uma licença para o seu trabalho, para que outras pessoas saibam em quais condições podem usar ou reproduzir ele. Para obter mais informações, consulte as Licenças Creative Commons.

Criar um novo repositório no Githubb

Para criar um novo repositório, faça login no Github e procure o botão verde para criar um novo repositório. Este repositório agora vazio pode ser clonado localmente em seu computador (consulte a próxima seção).

Você deve escolher se deseja que seu repositório seja público, ou seja, visível para todos na internet, ou privado, visível apenas para aqueles com permissão. Isso tem implicações importantes se seus dados forem confidenciais. Se o seu repositório for privado, você encontrará certas circunstâncias especiais avançadas, como se estiver usando as actions do Github para executar automaticamente o seu código na nuvem.

Clonar de um repositório Github

Você pode clonar um repositório Github existente para criar um novo projeto R local em seu computador.

O repositório Github pode ser algum que já existe (com conteúdo) ou pode ser um repositório vazio que você acabou de criar. Neste último caso, você está essencialmente criando o repositório Github e o projeto R local ao mesmo tempo (consulte as instruções acima).

Observação: se você não possui direitos de contribuição em um repositório Github, é possível primeiro bifurcar o repositório para o seu perfil, e então prosseguir com as outras ações. A bifurcação é explicada no final deste capítulo, mas recomendamos que você leia as outras seções primeiro.

Etapa 1: no Github, navegue até o repositório, clique no botão verde “Code” e copie a URL clone HTTPS (veja a imagem abaixo)

A próxima etapa pode ser realizada em qualquer interface. Vamos ilustrar com o Rstudio desktop e com o Github.

No Rstudio

No RStudio, comece um novo projeto R clicando em File>New Project>Version Control>Git

Quando for solicitada a “URL do repositório”, cole a URL HTTPS do Github
Atribua ao projeto R um nome curto e informativo
Escolha onde o novo Projeto R será salvo localmente
Marque “Abrir em nova sessão” e clique em “Criar projeto”

Agora você está em um novo projeto RStudio local que é um clone do repositório Github. O projeto local e o repositório Github agora estão vinculados.

No Github Desktop

Clique em Arquivo > Clonar um repositório
Selecione a guia URL
Cole a URL HTTPS do Github na primeira caixa
Selecione a pasta na qual deseja ter seu repositório local
Clique em “CLONE”

Novo repositório Github a partir de um projeto R existente

Outro cenário de configuração alternativo ocorre quando você tem um projeto R existente com conteúdo e deseja criar um repositório Github para ele.

Crie um novo repositório Github vazio para o projeto (consulte as instruções acima)
Clone este repositório localmente (consulte as instruções HTTPS acima)
Copie todo o conteúdo de seu projeto R pré-existente (códigos, dados, etc.) para este novo repositório vazio e local (Ex.: use copiar e colar).
Abra seu novo projeto no RStudio e vá para o painel Git. Os novos arquivos devem estar registrados como alterações de arquivo, agora rastreados pelo Git. Portanto, você pode agrupar essas alterações como um commit e enviar para o Github. Uma vez enviado, o repositório no Github refletirá todos os arquivos.

Consulte a seção de fluxo de trabalho do Github abaixo para obter detalhes sobre esse processo.

Como aparecem agora?

No RStudio

Depois de clonar um repositório Github para um novo projeto R, você verá no RStudio uma guia “Git”. Esta guia aparece no mesmo painel RStudio que seu “ambiente”Environment” R:

Observe os botões circulados na imagem acima, pois eles serão comentados a seguir (da esquerda para a direita):

Botão commit para confirmar as alterações do arquivo salvo no branch local (isso abrirá uma nova janela)
Seta azul para extrair (atualize sua versão local do branch com quaisquer alterações feitas na versão Github (remota) desse branch)
Seta verde para enviar (atualize quaisquer commits / alterações da sua versão local do branch para a versão Github (remota) desse branch)
A guia Git no RStudio
Botão para criar um NOVO branch usando qualquer branch local (mostrado à direita como base). Quase sempre você criará um branch a partir do branch principal (depois de extrair pela primeira vez para atualizar o branch principal)
O branch que você está trabalhando no momento
Alterações feitas no código ou em outros arquivos aparecerão abaixo

No Github Desktop

Github Desktop é um aplicativo independente que permite gerenciar todos os seus repositórios. Ao abri-lo, a interface permite que você escolha o repositório no qual deseja trabalhar e, a seguir, executar ações básicas do Git a partir dele.

46.6 Fluxo de trabalho Git + Github

Visão geral do processo

Depois de concluir a configuração (descrita acima), você terá um repositório Github conectado (clonado) a um projeto R local. O branch principal (criado por padrão) é a versão chamada “ao vivo” de todos os arquivos. Quando você quiser fazer modificações, é uma boa prática criar um novo branch a partir do branch principal (“Fazer uma cópia”). Este é um fluxo de trabalho típico no Git porque criar um branch é fácil e rápido.

Um fluxo de trabalho típico é o seguinte:

Certifique-se de que seu repositório local está atualizado e, se não estiver, atualize;
Vá para o branch em que você estava trabalhando anteriormente ou crie um novo branch para testar algumas coisas
Trabalhe nos arquivos localmente em seu computador, faça um ou vários commits para este branch
Atualize a versão remota da filial com suas alterações (enviar)
Quando estiver satisfeito com seu branch, você pode mesclar a versão online do branch que trabalhou para o branch “principal” on-line e, assim, transferir suas alterações

Outros membros da equipe podem estar fazendo a mesma coisa com seus próprios branches, ou talvez contribuindo com commits no branch que você está trabalhando também.

Vamos repassar passo a passo do processo acima com mais detalhes abaixo. Aqui está um esquema que desenvolvemos - está no formato de uma tabela dois-por-dois, portanto, deve ajudar os epidemiologistas a entender.

Aqui está outro diagrama.

Observação: até recentemente, o termo branch “master” era usado, mas agora é chamado de branch “main” (principal).

Fonte da imagem

46.7 Crie um novo branch

Quando você seleciona um branch para trabalhar, Git redefine seu diretório de trabalho do jeito que estava da última vez que você esteve neste branch.

No painel Git no Rstudio

Certifique-se de que está no branch “principal” e clique no ícone roxo para criar um novo branch (veja a imagem acima).

Você deverá nomear seu branch com uma única palavra (pode usar sublinhado, se necessário).
Você verá que localmente está no mesmo projeto R, mas não está mais trabalhando no branch “main”.
Depois de criado, o novo branch também aparecerá no site do Github como um branch.

Você pode visualizar branches no painel Git no Rstudio depois de clicar em “Histórico”

No Github Desktop

O processo é muito semelhante, você deverá dar um nome ao seu branch. Depois, você será solicitado a “Publicar seu branch no Github” para fazer o novo branch aparecer no repositório remoto também.

No console

O que realmente está acontecendo nos bastidores é que você cria um novo branch com git branch, então vai para o branch comgit checkout (_isto é, diga ao Git que seus próximos commits ocorrerão lá). Do seu repositório git:

git branch my-new-branch  # Cria o novo branch
git checkout my-new-branch # Vai para o branch
git checkout -b my-new-branch # Os dois ao mesmo tempo (atalho)

Para obter mais informações sobre como usar o console, consulte a seção sobre comandos Git no final.

46.8 Confirmar alterações

Agora você pode editar o código, adicionar novos arquivos, atualizar conjuntos de dados, etc.

Cada uma de suas alterações será rastreada, uma vez que o respectivo arquivo for salvo. Os arquivos alterados irão aparecer na aba Git do RStudio, no Github , ou usando o comando git status no terminal (veja abaixo).

Sempre que você fizer alterações substanciais (Ex.:, adicionar ou atualizar uma seção de código), pare e confirme essas alterações (commit). Pense em um commit como um “lote” de mudanças relacionadas a um propósito comum. Você poderá continuar revisan um arquivo mesmo após ter confirmado as alterações nele.

Conselhos sobre commits: geralmente, é melhor fazer pequenos commits, que podem ser facilmente revertidos se um problema surgir, para confirmar modificações diferentes relacionadas a um mesmo propósito. Para isso, você descobrirá que deve criar commits com frequência. No início, você provavelmente vai esquecer, mas logo desenvolverá o hábito.

No Rstudio

O exemplo abaixo mostra que, desde o último commit, o script R Markdown “Collaboration.Rmd” mudou, e várias imagens PNG foram adicionadas.

Você pode estar se perguntando o que representam os quadrados amarelos, azuis, verdes e vermelhos próximos aos nomes dos arquivos. Aqui está uma parte do Cheatsheet RStudio que explica seu significado. Mudanças com o quadrado amarelo (“?”) ainda podem ser preparadas, confirmadas e enviadas.

Pressione o botão “Commit” na guia Git, que abrirá uma nova janela (reproduzida abaixo)
Clique no nome de um arquivo na caixa superior esquerda
Revise as alterações feitas no arquivo (destacadas abaixo em verde ou vermelho)
“Prepare” o arquivo, que incluirá essas mudanças no commit. Faça isso marcando a caixa ao lado do nome do arquivo. Como alternativa, você pode destacar vários nomes de arquivo e clicar em “Stage”
Escreva uma mensagem de confirmação que seja curta, mas descritiva (obrigatório)
Pressione o botão “Commit”. Uma caixa pop-up aparecerá mostrando o sucesso ou uma mensagem de erro.

Agora você pode fazer mais alterações e mais commits, quantas vezes quiser

No Github Desktop

Você pode ver a lista dos arquivos que foram alterados à esquerda. Se você selecionar um arquivo de texto, verá um resumo das modificações feitas no painel direito (a visualização não funcionará em arquivos mais complexos como .docs ou .xlsx).

Para fazer as alterações, basta marcar a caixa ao lado dos nomes dos arquivos. Quando você tiver selecionado os arquivos que deseja adicionar a este commit, dê um nome ao commit, uma descrição (opcional) e clique no botão commit.

No console

São usadas as funções git add para selecionar / preparar arquivos egit commit para realmente fazer o commit.

git status #veja as mudanças 

git add new_pages/collaboration.Rmd  # selecione arquivos para o commit (= "stage" mudanças)

git commit -m "Describe commit from Github Desktop" # confirme mudanças com uma mensagem

git log  # veja informações sobre commits anteriores

Corrigir um commit anterior

O que acontece se você fizer o commit de algumas alterações, continuar trabalhando e perceber que fez alterações que deveriam “pertencer” ao commit anterior (na sua opinião)? Está tudo bem! Você pode anexar essas alterações ao seu commit anterior.

No Rstudio há uma caixa “Corrigir commit anterior” na mesma linha do botão COMMIT.

Por alguma razão, esta funcionalidade não foi implementada da mesma forma no Github Desktop, mas há uma maneira de contornar (estranha, mas fácil!). Se você tiver confirmado suas alterações mas não enviado ainda, um botão “UNDO” aparecerá logo abaixo do botão COMMIT. Clique nele e ele irá reverter seu commit (mas mantenha seus arquivos preparados e sua mensagem de commit). Salve suas mudanças, adicione novos arquivos ao commit se necessário e faça o commit novamente.

No console:

git add [SEUS ARQUIVOS] # Prepare suas novas mudanças

git commit --amend  # Corrija o commit anteriororrigir o commit anterior

git commit --amend -m "An updated commit message"  # Corrija o commit anterior E atualize a mensagem de commit

Observação: pense antes de modificar commits que já são públicos e compartilhados com seus colaboradores.

46.9 Pull (baixar/extrair) e Push (enviar/subir) alterações para o Github

“Primeiro PULL, depois PUSH”

É uma boa prática fetch (buscar) e pull (baixar) antes de começar a trabalhar no seu projeto, para atualizar a versão do branch em seu computador local com quaisquer alterações que tenham sido feitas na versão remota / Github.

PULL frequentemente. Não hesite. Sempre faça um pull antes de fazer um push.

Quando suas mudanças forem feitas e confirmadas e você estiver feliz com o seu projeto, você pode fazer um push dos seus commits para a versão remota / Github de seu branch.

Observação: é muito mais fácil desfazer alterações que foram confirmadas, mas não enviadas (ou seja, ainda são locais) do que alterações que foram enviadas para o repositório remoto (e talvez já extraídas por outra pessoa), por isso é melhor enviar quando terminar de introduzir mudanças no estava trabalhando.

No Rstudio

PULL - Primeiro, clique no ícone “Pull” (seta azul para baixo) que busca e extrai ao mesmo tempo.

PUSH - Clique no ícone “Pull” (seta verde para cima). Pode ser necessário inserir seu nome de usuário e senha do Github. Na primeira vez que você for solicitado, pode ser necessário inserir duas linhas de comando Git no Terminal:

git config –global user.email “voce@exemplo.com” (seu endereço de email Github), e
git config –global user.name “Seu nome de usuário Github”

Para saber mais sobre como inserir esses comandos, consulte a seção abaixo sobre comandos Git.

DICA: Sua senha está sendo solicitada com muita frequência? Veja os capítulos 10 e 11 deste tutorial para se conectar a um repositório usando uma chave SSH (mais complicado)

No Github Desktop

Clique no botão “Buscar origem” para verificar se há novos commits no repositório remoto.

Se o Git encontrar novos commits no repositório remoto, o botão mudará para um botão “Pull”. Como o mesmo botão é usado para fazer o pull (baixar/extrair) e fazer o push (subir/enviar), você não pode enviar suas alterações se não fizer o pull antes.

Você pode ir para a guia “Histórico” (perto da guia “Alterações”) para ver todos os commits (seus e dos outros). Essa é uma ótima maneira de se familiarizar com o que seus colaboradores fizeram. Você pode ler a mensagem de confirmação, a descrição, se houver, e comparar o código dos dois arquivos usando o painel diff.

Uma vez que todas as mudanças remotas tenham sido extraídas, e pelo menos uma mudança local tenha sido confirmada, você pode enviar clicando no mesmo botão.

Console

Como esperado, os comandos são fetch, pull e push .

git fetch  # Existem novos commits no diretório remoto?
git pull   # Traga commits remotos para seu branch local
git push   # Envie commits locais deste branch para o branch remoto

Quero fazer um pull, mas tenho trabalho local

Isso pode acontecer às vezes: você fez algumas mudanças em seu repositório local, mas o repositório remoto tem commits que você não extraiu.

O Git se recusará a fazer um pull porque pode sobrescrever suas alterações. Existem várias estratégias para manter suas mudanças, bem descritas em Happy Git with R, entre as quais as duas principais são:

confirme suas alterações, busque alterações remotas, extraia elas, resolva conflitos, se necessário (consulte a seção abaixo), e coloque tudo online
stash suas alterações, que meio que as armazena à parte, extrai, restaura (“unstash”) e então efetua o commit, resolvendo quaisquer conflitos e envia.

Se não houver sobreposição entre os arquivos das mudanças remotas e os arquivos das mudanças locais, o Git pode resolver os conflitos automaticamente.

No Github Desktop, isso pode ser feito com botões. Para isso, vá até Branch> Stash all changes.

46.10 Mesclar no branch principal

Se você concluiu as alterações, pode iniciar o processo de mesclagem dessas alterações no branch principal. Dependendo da situação, isso pode ser rápido ou contemplar etapas acordadas de revisão e aprovação envolvendo colegas da sua equipe.

Localmente no Github Desktop

É possível mesclar branches localmente usando o Github Desktop. Primeiro, vá até o branch que será o destinatário dos commits, ou seja, o branch que você deseja atualizar. Em seguida, clique em Branch > Merge into current branch. Uma caixa permitirá que você selecione o branch que deseja importar.

No console

Primeiro, volte para o branch que receberá as alterações. Geralmente é o master, mas pode ser outro branch. Em seguida, mescle seu branch de trabalho no master.

git checkout master  # Volte para o master (ou para o branch que você deseja mover)
git merge this_fancy_new_branch

Esta página mostra um exemplo mais avançado de branching e explica um pouco como funciona nos bastidores.

No Github: submeter uma requisição de pull

Embora seja totalmente possível mesclar dois branches localmente, ou sem informar ninguém, uma mesclagem pode ser discutida ou investigada por várias pessoas antes de ser integrada ao branch master. Para ajudar no processo, o Github oferece alguns recursos de discussão sobre a mesclagem: a solicitação de pull.

Uma solicitação de pull (um “PR”, do inglês pull request) é uma solicitação para mesclar um branch em outro (em outras palavras, uma solicitação para que _seu branch de trabalho seja extraído para o branch “main”). Uma solicitação de extração geralmente envolve vários commits e inicia uma conversa, um processo de revisão, antes de ser aceita e o branch ser mesclado. Por exemplo, você pode ler as discussões de solicitação de extração no github do dplyr.

Você pode enviar uma solicitação de pull (PR) diretamente do site (conforme ilustrado abaixo) ou do Github Desktop.

Vá para o repositório Github (online)
Visualize a guia “Solicitações de pull” e clique no botão “Nova solicitação de pull”
Selecione no menu suspenso para mesclar seu branch no branch principal (main)
Escreva um comentário detalhado sobre o Pull Request e clique em “Criar Pull Request”.

Agora você será capaz de ver a solicitação pull (exemplo na imagem abaixo):

Revise a guia “Arquivos alterados” para ver como o branch “main” mudaria se o branch fosse mesclado.
À direita, você pode solicitar uma revisão dos colaboradores da sua equipe marcando seus IDs no Github. Se desejar, você pode definir as configurações do repositório para exigir uma revisão de aprovação antes de mesclar com o main.
Assim que a solicitação pull for aprovada, um botão para “Mesclar solicitação pull” ficará ativo. Clique nele.
Depois de concluído, exclua seu branch conforme explicado abaixo.

Resolvendo conflitos

Quando duas pessoas modificam a (s) mesma (s) linha (s) ao mesmo tempo, surge um conflito de mesclagem. Na verdade, o Git se recusa a tomar uma decisão sobre qual versão manter, mas ajuda a descobrir onde está o conflito. NÃO ENTRE EM PÂNICO. Na maioria das vezes, é muito simples de resolver.

Por exemplo, no Github:

Após a mesclagem gerar um conflito, abra o arquivo em seu editor favorito. O conflito será indicado por uma série de caracteres:

O texto entre <<<<<<<HEAD e ======= vem do seu repositório local, já o texto entre ======= e >>>>>>> vem do outro branch (que pode ser o original, o master ou qualquer branch de sua escolha).

Você precisa decidir qual versão do código prefere (ou até mesmo escrever uma terceira, incluindo alterações de ambos os lados, se pertinente), excluir o resto e remover todas as marcas que o Git adicionou (<<<<<<<HEAD,=======,>>>>>>>origin/master/your_branch_name).

Então, salve, prepare e submeta o arquivo: este é o commit que torna a versão mesclada “oficial”. Não se esqueça de enviar depois.

Quanto mais você e seus colaboradores puxarem e empurrarem, menores serão os conflitos.

Observação: se você se sentir à vontade com o console, há mais opções avançadas de mesclagem (Ex.: ignorando espaços em branco, dando prioridade a um colaborador, etc.).

Delete seu branch

Depois que um branch foi mesclado com o master e não for mais necessário, você pode excluí-lo.

46.10.0.1 Github + Rstudio

Vá até o repositório no Github e clique no botão para ver todos os branches (próximo ao menu suspenso para selecionar branches). Agora encontre seu branch e clique no ícone de lixeira próximo a ele. Leia mais detalhes sobre como excluir um branch aqui.

Certifique-se de excluir também o branch local no seu computador. Isso não acontecerá automaticamente.

No RStudio, certifique-se de estar no branch principal
Passe a digitar comandos Git no “Terminal” do RStudio (a guia adjacente ao console R) e digite: git branch -d nome_do_branch , onde “nome_do_branch” é o nome do seu branch a ser excluído
Atualize sua guia Git e o branch terá desaparecido

46.10.0.2 No Github Desktop

Basta verificar o branch que deseja excluir e ir até o menu Branch>Delete.

Forking

Você pode bifurcar um projeto (fork) se desejar contribuir com ele mas não tiver os direitos ou se desejar modificá-lo apenas para seu uso pessoal. Uma breve descrição da bifurcação pode ser encontrada aqui.

No Github, clique no botão “Fork”:

Isso irá clonar o repositório original no seu próprio perfil. Agora, existem duas versões do repositório no Github: a original, que você não pode modificar, e a versão clonada no seu perfil.

Em seguida, você pode clonar sua versão do repositório online localmente no seu computador, usando qualquer um dos métodos descritos nas seções anteriores. A partir de então, você poderá criar um novo branch, fazer mudanças, submetê-las e enviá-las para o seu repositório remoto.

Quando estiver satisfeito com o resultado, você pode criar um “Pull Request” do Github ou Github Desktop para iniciar a conversa com os proprietários / responsáveis pelo repositório original.

E se você precisar de alguns commits mais recentes do repositório original?

Imagine que alguém faça uma modificação substancial no repositório oficial, que você deseja incluir em sua versão clonada. É possível sincronizar sua bifurcação (fork) com o repositório oficial. Envolve o uso do terminal, mas não é tão complicado. Você precisa se lembrar principalmente que: - upstream = repositório oficial, aquele que você não pode modificar - origin = sua versão do repositório em seu perfil Github

Você pode ler este tutorial ou seguir o caminho abaixo:

Primeiro, digite seu terminal Git (dentro de seu reposositório):

git remote -v

Se você ainda não configurou o repositório upstream, deverá ver duas linhas, começando por origin. Eles mostram o repositório remoto para o qual fetch epush estão direcionados. Lembre-se, por convenção, origin é sua própria versão do repositório no Github. Por exemplo:

Agora, adicione um novo repositório remoto:

git remote add upstream https://github.com/appliedepi/epirhandbook_eng.git

Aqui, o site é o endereço que o Github gera quando você clona um repositório (consulte a seção sobre clonagem). Agora você terá quatro ponteiros remotos:

Agora que a configuração está feita, sempre que você quiser obter as alterações do repositório original (upstream), você só precisa ir (checkout) ao branch que deseja atualizar e digitar:

git fetch upstream # Para obter os novos commits do repositório remoto
git checkout the_branch_you_want_to_update
git merge upstream/the_branch_you_want_to_update  # Para mesclar o branch upstream em seu branch
git push # Para atualizar sua própria versão do repositório remoto

Se houver conflitos, você terá que resolvê-los, conforme explicado na seção Resolvendo conflitos.

Resumo: bifurcar é clonar, mas no servidor Github. O restante das ações são ações típicas do fluxo de trabalho de colaboração (clonar, enviar, puxar, confirmar, mesclar, enviar solicitações pull …).

Observação: a bifurcação é um conceito, não um comando Git, e também existe em outros sites de hospedagem, como Bitbucket.

46.11 O que aprendemos

Você aprendeu como:

configurar o Git para rastrear modificações em suas pastas,
conectar seu repositório local a um repositório online remoto,
confirmar alterações,
sincronizar seus repositórios locais e remotos.

Isso deve ajudá-lo e ser suficiente para a maioria de suas demandas como epidemiologista. Normalmente não temos um uso tão avançado quanto os desenvolvedores.

No entanto, se você quiser (ou precisar) ir além, o Git oferece funcionalidades para simplificar históricos de commits, reverter um ou vários commits, selecionar commits, etc. Alguns deles podem soar como pura magia, mas agora que você já sabe o básico, será mais fácil avançar.

Observe que embora o painel Git no Rstudio e no Github Desktop sejam bons para iniciantes ou para uso diário no trabalho, eles não oferecem interface para algumas das funções intermediárias e avançadas do Git. Algumas interfaces mais completas permitem fazer mais com cliques (geralmente ao custo de um layout mais complexo).

Lembre-se que você pode usar qualquer ferramenta para rastrear seu repositório, então pode instalar uma outra interface para experimentá-la algumas vezes, ou para realizar alguma tarefa complexa não tão comum no seu trabalho, e continuar usando uma interface simplificada para o resto do tempo (por exemplo, usando Github Desktop na maioria das vezes e mudando para SourceTree ou Gitbash para algumas tarefas específicas).

46.12 Comandos Git

Aprendizados recomendados

Para aprender os comandos Git em um tutorial interativo, consulte este site.

Onde inserir comandos

Você insere comandos em um shell Git.

Opção 1 Você pode abrir um novo Terminal no RStudio. Esta guia está ao lado do R Console. Se você não conseguir digitar nenhum texto nele, clique no menu suspenso abaixo de “Terminal” e selecione “Novo terminal”. Digite os comandos no espaço em frente do cifrão “$”.

Opção 2 Você também pode abrir um shell (um terminal para inserir comandos) clicando no ícone azul “engrenagens” na guia Git (próximo ao ambiente RStudio). Selecione “Shell” no menu suspenso. Uma nova janela será aberta onde você pode digitar os comandos após o cifrão “$”.

Opção 3 Clique com o botão direito para abrir o “Git Bash aqui”, que abrirá o mesmo tipo de terminal, ou abra o Git Bash da sua lista de aplicativos. Mais informações para iniciantes no Git Bash, como encontrá-lo e alguns comandos bash que você precisará.

Amostra de comandos

Abaixo, apresentamos alguns comandos git comuns. Ao usá-los, lembre-se de qual branch está ativo (com check-out), pois isso mudará a ação!

Nos comandos abaixo, representa o nome de um branch. representa o ID de hash de um commit específico. representa um número. Não digite os símbolos < ou >.

Comando Git	Ação
`git branch <nome>`	Crie uma nova ramificação com o nome
`git checkout <nome>`	Mude o branch (ramificação) atual para
`git checkout -b <nome>`	Atalho para criar um novo branch e mudar para ele
`git status`	Veja as alterações não rastreadas
`git add <file>`	Prepare um arquivo
`git commit -m <message>`	Confirme as alterações (commit) preparadas para o branch atual com a mensagem
`git fetch`	Obter commits do repositório remoto
`git pull`	Extraia commits do repositório remoto no branch atual
`git push`	Envie commits locais para o diretório remoto
`git switch`	Uma alternativa ao `git checkout` que está sendo implementado no Git
`git merge <nome>`	Mescle o branch no branch atual
`git rebase <nome>`	Anexar commits do branch atual para o branch

46.13 Recursos

Grande parte desta página foi baseada no site “Happy Git with R” de Jenny Bryan. Há uma seção muito útil neste site que ajuda a solucionar erros comuns relacionados ao Git e ao R.

Documentação do Github.com e guia de inicialização.

“IDE” cheatsheet do RStudio que inclui dicas sobre o uso do Git com RStudio.

https://ohi-science.org/news/github-going-back-in-time

Comandos Git para iniciantes

Um tutorial interativo para aprender os comandos Git.

https://www.freecodecamp.org/news/an-introduction-to-git-for-absolute-beginners-86fa1d32ff71/: “básico do básico” para rastrear alterações em uma pasta no seu próprio computador.

Esquemas legais para entender os branches: https://speakerdeck.com/alicebartlett/git-for-humans

Tutoriais de assuntos básicos e avançados

https://tutorialzine.com/2016/06/learn-git-in-30-minutes
https://dzone.com/articles/git-tutorial-commands-and-operations-in-git
https://swcarpentry.github.io/git-novice/ (short course)
https://rsjakob.gitbooks.io/git/content/chapter1.html

O livro Pro Git é considerado uma referência oficial. Mas embora alguns capítulos estejam ok, ele pode parecer um pouco técnico. Certamente será um bom recurso se você já tiver usado um pouco o Git e quiser aprender um pouco mais precisamente sobre o que acontece e como ir mais longe.