Introdução ao Controle de Versão com Git. Software Carpentry

Transcrição

1 Introdução ao Controle de Versão com Git Software Carpentry

2 2

3 Sumário 1 Introdução ao Controle de Versão com Git 7 Pré-requisitos Tópicos Outros recursos Configurando o Git 9 Objetivos Proxy Criando um repositório 13 Objetivos Onde posso criar meu repositório? Monitorando alterações 15 Objetivos Onde estão minhas mudanças? Comitando alterações no Git Repositório bio Explorando o histórico 25 Objetivos Simplificando o Caso Comum Recuperando versões antigas de um arquivo

4 4 SUMÁRIO 6 Ignorando Arquivos 31 Objetivos Colaborando 35 Objetivos HTTPS vs SSH Proxy Gerenciadores de Senhas A opção -u Praticando sozinho Marcação de tempo no GitHub Conflitos 45 Objetivos Resolvendo conflitos que você criou Conflitos em arquivos que não são texto plano Ciência Aberta 51 Objetivo Controle de versão de cadernos de anotações científicos eletrônicos.. 52 Licenciamento Licenciamento de produtos que não são programas de computador 54 Hospedagem Posso utilizar uma licença aberta? Posso utilizar uma licença aberta? Meu trabalho pode ser público? Motivação 59 Por que utilizar Controle de Versão? Por que Git? Próximos Passos

5 SUMÁRIO 5 11 Referência 61 Configurando o Git Criando um repositório Monitorando alterações Explorando o histórico Ignorando Arquivos Colaborando Conflitos Ciência Aberta Glossário Discussão 65 Frequently Asked Questions More Advanced Git Configuration Styling Git s Log Version Controlling the Gitconfig Non-text Files Non-text Version Control Guia para Instrutores 71 Legend Overall Teaching Notes Setting Up Git Creating a Repository Tracking Changes Exploring History Ignoring Things Collaborating Conflicts Open Science

6 6 SUMÁRIO 14 Licença 75 Material Software Trademark

7 Capítulo 1 Introdução ao Controle de Versão com Git Lobisomem e Drácula foram contratados pelo Universal Missions (uma agência de serviços espaciais da Euphoric State University) para descobrir onde a companhia deveria enviar sue próximo robô explorador. Eles desejam trabalhar nos planos ao mesmo tempo mas tiveram problemas ao fazer isso no passado. Se eles trabalharem em turnos, cada um deles irá gastar muito tempo esperando o outro terminar mas se eles trabalharem em sua cópia e trocarem s com as mudanças alguma coisa acabará se perdendo, sendo reescrita ou duplicada. A solução é eles utilizarem controle de versão para gerenciar o trabalho. Controle de versão é melhor que trocar arquivos por pois: Nada que é salva no controle de versão pode ser perdido. Isso significa que ele pode ser utilizado como a ferramenta desfazer de um editor de texto e como todas as versões anteriores dos arquivos estão salvas sempre é possível voltar no tempo para saber quem escreveu o que em um dia particular ou que versão de um programa foi utilizado para gerar um resultado. Ele mantem um registro de quem fez cada mudança e quando ela foi feita e assim, se alguém tiver perguntas depois saberá a quem perguntar. É difícil (mas não impossível) de acidentalmente sobrescrever as mudanças de alguém: o sistema de controle de versão automaticamente avisa o usuário quando existe um conflito entre o trabalho de duas ou mais pessoas. Controle de versão é o caderno de laboratório do mundo digital: é o que profissionais utilizam para manter registro do que fizeram e para colaborar com outras pessoas. Todo grande projeto de desenvolvimento de software depende dele, e vários programadores também o utilizam para seus pequenos projetos. E ele não é utilizado apenas para software: livros (como esse), artigos, pequenos 7

8 8 CAPÍTULO 1. INTRODUÇÃO AO CONTROLE DE VERSÃO COM GIT conjuntos de dados, e qualquer coisa que é modificado ao longo do tempo ou precisa ser compartilhada pode e deveria ser armazenado em um sistema para controle de versão. Pré-requisitos Nessa lição utilizamos Git pela linha de comando e por isso espera-se uma experiência prévia com ela embora isso não seja obrigatório. Tópicos 1. Configurando o Git 2. Criando um repositório 3. Monitorando alterações 4. Explorando o histórico 5. Ignorando Arquivos 6. Colaborando 7. Conflitos 8. Ciência Aberta Outros recursos Motivação Referência Discussão Guia do Instrutor

9 Capítulo 2 Configurando o Git Objetivos Explicar os passos de inicialização e configuração necessários por máquina e por repositório. Nós vamos começar explorando como o controle de versão pode ser utilizado para manter o registro do que e de quando uma pessoa fez algo. Mesmo se você não estiver colaborando com outros, controle de versão é muito melhor que: 9

10 10 CAPÍTULO 2. CONFIGURANDO O GIT Piled Higher and Deeper by Jorge Cham, Na primeira vez que utilizamos Git em uma máquina, precisamos configurar algumas coisas. A seguir encontra-se o que Drácula fez para configurar seu novo notebook: $ git config --global user.name "Vlad Dracula"

11 PROXY 11 $ git config --global user. "[email protected]" $ git config --global color.ui "auto" (Por favor, utilize seu nome e endereço de ao invés do de Drácula) Ele também configurou seu editor favorito utilizando a tabela a seguir. Editor nano Text Wrangler Sublime Text (Mac) Sublime Text (Win) Notepad++ (Win) Kate (Linux) Gedit (Linux) Configuration command $ git config --global core.editor "nano -w" $ git config --global core.editor "edit -w" $ git config --global core.editor "subl -n -w" $ git config --global core.editor "'c:/program files/sublime text 2/sublime_te $ git config --global core.editor "'c:/program files (x86)/notepad++/notepad++ $ git config --global core.editor "kate" $ git config --global core.editor "gedit -s" Os commandos do Git são escritos como git verbo, onde verbo é o que desejamos fazer. No caso anterior, estamos dizendo para o Git: nosso nome e endereço de , para colorir a saída, qual o nosso editor de texto favorito, e que queremos utilizar essas informações globalmente (i.e., para todo projeto). Os quatro comandos anteriores só precisam ser executados uma vez: a opção (em inglês denominada de flag) --global diz para o Git utilizar as configurações para todo projeto na máquina atual. You can check your settings at any time: $ git config --list Proxy Em alguns casos você precisa utilizar um proxy para se conectar a internet. Se esse for o seu caso você precisa informar o Git sobre o proxy: $ git config --global http.proxy proxy-url $ git config --global https.proxy proxy-url Para desabilitar o proxy, utilize

12 12 CAPÍTULO 2. CONFIGURANDO O GIT $ git config --global --unset http.proxy $ git config --global --unset https.proxy

13 Capítulo 3 Criando um repositório Objetivos Explicar como criar um repositório Git local. Uma vez que Git está configurado, podemos começar a utilizá-lo. Vamos criar um diretório para nosso trabalho: $ mkdir planetas $ cd planetas e dizemos para fazer do diretório um repositório um lugar onde Git irá armazenar as versões anteriores de nossos arquivos: $ git init Se utilizarmos ls para mostrar o conteúdo do diretório irá parecer que nada foi feito: $ ls Mas se adicionarmos a opção -a para mostrar todos os arquivos, iremos ver que Git criou um diretório oculto denominado.git: $ ls -a....git 13

14 14 CAPÍTULO 3. CRIANDO UM REPOSITÓRIO Git armazena informações sobre o projeto nesse subdiretório especial. Se deletarmos ele iremos perder o histórico do projeto. Podemos verificar que a configuração foi feita com sucesso requisitando o estado do nosso projeto para o Git: $ git status # On branch master # # Initial commit # nothing to commit (create/copy files and use "git add" to track) Onde posso criar meu repositório? A seguinte sequencia de comandos cira um repositório Git dentro de outro: cd mkdir alpha cd alpha git init mkdir beta cd beta git init # retorna para sua pasta de usuário # cria um novo repositório # muda o diretório atual para o diretório recém criado # transforma o diretório recém criado em um repositório Git # cria um subdiretório # muda o diretório atual para o subdiretório recém criado # transforma o subdiretório em um repositório Git Por que utilizar um repositório Git dentro de outro é uma péssima ideia?

15 Capítulo 4 Monitorando alterações Objetivos Passar o ciclo modicar-adicionar-salvar para um único arquivo e para múltiplos arquivos. Explicar onde a informação é armazenada em cada estágio. Vamos criar um arquivo chamado marte.txt que contém algumas notas sobre a sustentabilidade de uma base no planeta vermelho. (Iremos utilizar um editor chamado nano para editar o arquivo mas você pode utilizar o editor de sua preferência. Em particular, ele não precisa ser o mesmo editor informado para o Git). $ nano marte.txt Escreva o texto abaixo no arquivo marte.txt: Frio e seco, mas tudo é da minha cor favorita. marte.txt agora contem a seguinte linha: $ ls marte.txt $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. 15

16 16 CAPÍTULO 4. MONITORANDO ALTERAÇÕES Se verificarmos o estado do nosso projeto novamente, Git irá informar que ele encontrou um novo arquivo: $ git status # On branch master # # Initial commit # # Untracked files: # (use "git add <file>..." to include in what will be committed) # # marte.txt nothing added to commit but untracked files present (use "git add" to track) A mensagem untracked files significa que existe um arquivo no diretório que Git não está monitorando. Iremos dizer para o Git que ele deve fazê-lo utilizando git add: $ git add marte.txt e então verificamos alteração na mensagem de estado: $ git status # On branch master # # Initial commit # # Changes to be committed: # (use "git rm --cached <file>..." to unstage) # # new file: marte.txt # Git agora sabe que ele deve monitorar o arquivo marte.txt mas ele ainda não salvou nenhuma mudança para a posterioridade como um commit. Para fazer isso precisamos executar mais um comando: $ git commit -m "Começando a tomar notas sobre Marte como um base" [master (root-commit) f22b25e] Começando a tomar notas sobre Marte como um base 1 file changed, 1 insertion(+) create mode marte.txt

17 ONDE ESTÃO MINHAS MUDANÇAS? 17 Quando executamos git commit, Git pega todas as mudanças que informamos precisar serem salvas quando utilizamos git add e armazena uma cópia permanente dentro do diretório especial.git. Essa cópia permanente é denominada revisão é brevemente identificada por f22b25e. (Sua revisão pode ter um identificador diferente.) Utilizamos a opção -m (de mensagem ) para salvar um pequeno comentário que seja descritivo e específico que irá nos ajudar a lembrar depois o que fizemos e porque. Se apenas executarmos git commit sem a opção -m, Git irá iniciar nano (ou o editor que tivermos configurado no início) para que possamos escrever um comentário longo. Boas mensagens de commit iniciam com um curto sumário (menos de 50 caracteres) das alterações feitas no commit. Se você desejar adicionar mais detalhes, adicione uma linha em branco entre o sumário e suas notas adicionais. Se executarmos git status agora: $ git status # On branch master nothing to commit, working directory clean Git está dizendo que tudo está atualizado. Se desejarmos saber o que foi feito recentemente podemos pedir ao Git que mostre o histórico do projeto utilizando git log: $ git log commit f22b25e3233b4645dabd0d81e651fe074bd8e73b Author: Vlad Dracula <[email protected]> Date: Thu Aug 22 09:51: Começando a tomar notas sobre Marte como um base git log lista todas as revisões salvas em um repositório na ordem cronológica reversa. Essa lista inclui, para cada revisão, o identificador completo da revisão (que inicia com os mesmos caracteres que o identificador curto impresso pelo comando git commit anteriormente), o autor da revisão, quando ela foi criada e o comentário dado à revisão quando ela foi criada. Onde estão minhas mudanças? Se executarmos ls agora continuamos a encontrar apenas um arquivo chamado marte.txt. Isso deve-se ao fato do Git salvar as informações

18 18 CAPÍTULO 4. MONITORANDO ALTERAÇÕES com histórico dos arquivos no diretório especial denominado.git mencionado anteriormente tal que nosso sitema de arquivos não fique cheio (e nós acidentalmente editemos ou removemos uma versão anterior. Agora suponha adicionou algumas informações ao arquivo. (Novamente, editaremos o arquivo utilizando o nano e utilizaremos o commando cat para mostrar o conteúdo do arquivo; você pode utilizar outro editor e não precisa do comando cat.) $ nano marte.txt $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Quando executamos o comando git status, ele irá informar que um arquivo sendo monitorado foi alterado: $ git status # On branch master # Changes not staged for commit: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: marte.txt # no changes added to commit (use "git add" and/or "git commit -a") A última linha, no changes added to commit, é importante e nos avisa que nenhuma das mudanças feitas será salvo na próxima revisão. Embora tenhamos alterado o arquivo não informamos ao Git que queremos salvar essas mudanças (que iremos fazer utilizando git add). Para verificar as alterações nos arquivos utilizamos git diff, que irá mostrar a diferença entre o estado atual dos arquivo e a última revisão salva: $ git diff diff --git a/marte.txt b/mars.txt index df0654a..315bf3a a/marte.txt Frio e seco, mas tudo é da minha cor favorita. +Duas luas pode ser um problema para o Lobisomem.

19 ONDE ESTÃO MINHAS MUDANÇAS? 19 A saída parecer criptografada porque na verdade é uma série de comandos dizendo para programas como editores de texto e patch como reconstruir um arquivo partindo do outro. Podemos quebrar essa saída em algumas partes: 1. A primeira linha informa que Git utilizou o comando diff para comparar a versão antiga com a nova. 2. A segunda linha informa exatamente quais revisões Git está comparando: df0654a e 315bf3a são identificadores únicos gerados pelo computador para essas duas revisões. 3. As linhas restantes mostram o que realmente mudou e as linhas correspondentes. Em particular, o sinal + na primeira coluna indica onde adicionamos novas linhas. Vamos salvar nossas mudanças: $ git commit -m "Adicionado preocupação sobre o feito das luas de Marte no Lobisomem" # On branch master # Changes not staged for commit: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: marte.txt # no changes added to commit (use "git add" and/or "git commit -a") Hoops: Git não salvou uma nova revisão porque esquecemos de utilizar o comando git add primeiro. Vamos corrigir isso: $ git add marte.txt $ git commit -m "Adicionado preocupação sobre o feito das luas de Marte no Lobisomem" [master 34961b1] Adicionado preocupação sobre o feito das luas de Marte no Lobisomem 1 file changed, 1 insertion(+) Git insiste que adicionemos os arquivos ao grupo a ser salvo antes de realmente criarmos uma nova revisão porque podemos não querer incluir todas as mudanças de uma vez. Por exemplo, suponha que estejamos adicionando algumas citações ao trabalho de nosso orientador na nossa tese. Pode ser que desejamos ter uma versão em que adicionamos as citações e as referências bibliográficas mas não desejamos incluir as mudanças na conclusão uma vez que ainda não terminamos esta. Para que isso seja possível, Git possui uma área temporária especial (em inglês denominada staging area) onde ele mantem o registro das alterações que foram

20 20 CAPÍTULO 4. MONITORANDO ALTERAÇÕES adicionadas ao conjunto a ser utilizado para o próximo commit (que ainda não foi feito). git add coloca as modificações nessa área e git commit move a informação dessa área para o armazenamento de longo termo na forma de um commit. Figura 4.1: The Git Staging Area Vamos verificar como nossas mudanças são transmitidas do nosso editor para a área temporária e posteriormente para o armazenamento de longo termo. Primeiro, precisamos adicionar uma nova linha ao arquivo: $ nano marte.txt $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Mas a Múmia irá apreciar a falta de humidade. $ git diff diff --git a/marte.txt b/mars.txt index 315bf3a..b36abfd a/marte.txt ,2 Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. +Mas a Múmia irá apreciar a falta de humidade. Até agora, tudo bem: adicionamos uma nova linha no final do arquivo (identificada com o sinal + na primeira coluna). Agora vamos colocar essa mudança na área temporária e verificar o que git diff informa:

21 ONDE ESTÃO MINHAS MUDANÇAS? 21 $ git add marte.txt $ git diff Não existe saída pois até onde o Git consegue informar não existe diferença entre o que foi pedido para salvar permanentemente e o arquivos no repositório. Entretanto, se pedirmos: $ git diff --staged diff --git a/marte.txt b/mars.txt index 315bf3a..b36abfd a/marte.txt ,2 Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. +Mas a Múmia irá apreciar a falta de humidade. será mostrado a diferença entre o último commit e as mudanças na área temporária. Vamos salvar nossa mudança: $ git commit -m "Discussão sobre o clima de Marte para a Múmia" [master f] Discussão sobre o clima de Marte para a Múmia 1 file changed, 1 insertion(+) e verificar o estado do repositório: $ git status # On branch master nothing to commit, working directory clean e também no histórico do que foi feito até agora: $ git log commit fbe2a98fb83f0ade869025dc2636b4dad5 Author: Vlad Dracula <[email protected]> Date: Thu Aug 22 10:14: Discussão sobre o clima de Marte para a Múmia

22 22 CAPÍTULO 4. MONITORANDO ALTERAÇÕES commit 34961b159c27df3b475cfe4415d94a6d1fcd064d Author: Vlad Dracula Date: Thu Aug 22 10:07: Adicionado preocupação sobre o feito das luas de Marte no Lobisomem commit f22b25e3233b4645dabd0d81e651fe074bd8e73b Author: Vlad Dracula <[email protected]> Date: Thu Aug 22 09:51: Começando a tomar notas sobre Marte como um base Para recapitular, quando queremos adicionar mudanças no nosso repositório, primeiro precisamos adicionar os arquivos alterados para a área de transferência (git add) e então commitar as mudanças na área de transferência no repositório (git commit): Comitando alterações no Git Qual comando abaixo irá salvar as alterações de meu-arquivo.txt no meu repositório Git local? 1. $ git commit -m minhas mudanças recentes 2. $ git init meu-arquivo.txt $ git commit -m minhas mudanças recentes 3. $ git add meu-arquivo.txt $ git commit -m minhas mudanças recentes 4. $ git commit -m meu-arquivo.txt minhas mudanças recentes Repositório bio Crie um novo repositório Git no seu computador chamado bio. Escreva uma versão curta da sua bibliografia com três linhas no arquivo me.txt, salva suas mudanças. Depois, modifique uma das linhas e adicione uma quarta linha, mostre a alteração feita e desfaçaa.

23 REPOSITÓRIO BIO 23 Figura 4.2: The Git Commit Workflow

24 24 CAPÍTULO 4. MONITORANDO ALTERAÇÕES

25 Capítulo 5 Explorando o histórico Objetivos Identificar e usar números de revisões do Git. Comparar versões antigas de um arquivo com a atual. Restaurar versões antigas de arquivos. Se desejarmos ver o que alteramos, podemos utilizar git diff novamente, mas referindo-se a versões antigas utilizando a notação HEAD~1, HEAD~2 e assim por diante: $ git diff HEAD~1 marte.txt diff --git a/marte.txt b/mars.txt index 315bf3a..b36abfd a/marte.txt ,2 Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. +Mas a Múmia irá apreciar a falta de humidade. $ git diff HEAD~2 marte.txt diff --git a/marte.txt b/mars.txt index df0654a..b36abfd a/marte.txt +++ b/marte.txt 25

26 26 CAPÍTULO 5. EXPLORANDO O -1 Frio e seco, mas tudo é da minha cor favorita. +Duas luas pode ser um problema para o Lobisomem. +Mas a Múmia irá apreciar a falta de humidade. Dessa forma, criamos uma sequência de revisões. A revisão mais recente nessa sequência é referenciada por HEAD e podemos referenciar revisões anteriores utilizando a notação com ~, tal que HEAD~1 (pronuncia-se head minus one ) significa a revisão anterior, enquanto HEAD~123 retorna 123 revisões do ponto em que estamos agora. Podemos também referenciar revisões anteriores utilizando a longa string de dígitos e letras impressas por git log. Essa longa string é única para as revisões e única realmente significa única: todo conjunto de mudanças em um conjunto de arquivos em cada máquina possui um identificador único de 40 caracteres. O nosso primeiro commit possui como identificado f22b25e3233b4645dabd0d81e651fe074bd8e73b. Então vamos tentar: $ git diff f22b25e3233b4645dabd0d81e651fe074bd8e73b marte.txt diff --git a/marte.txt b/mars.txt index df0654a..b36abfd a/marte.txt Frio e seco, mas tudo é da minha cor favorita. +Duas luas pode ser um problema para o Lobisomem. +Mas a Múmia irá apreciar a falta de humidade. A resposta do Git está correta mas digitar 40 caracteres aleatórios é inconveniente e por isso Git permite você digitar apenas os primeiros caracteres: $ git diff f22b25e marte.txt diff --git a/marte.txt b/mars.txt index df0654a..b36abfd a/marte.txt Frio e seco, mas tudo é da minha cor favorita. +Duas luas pode ser um problema para o Lobisomem. +Mas a Múmia irá apreciar a falta de humidade. Até agora aprendemos como salvar alterações nos arquivos e verificar as alterações realizadas. Como podemos recuperar um arquivo de uma versão antiga? Vamos supor que acidentalmente sobre escrevemos um de nossos arquivos.

27 OBJETIVOS 27 $ nano marte.txt $ cat marte.txt Teremos que produzir oxigênio para nosso consumo. git status irá informar que os arquivo foi alterado e que as alterações não foram salvas na área temporária: $ git status # On branch master # Changes not staged for commit: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: marte.txt # no changes added to commit (use "git add" and/or "git commit -a") Podemos desfazer as mudanças utilizando o comando git checkout: We can put things back the way they were by using git checkout: $ git checkout HEAD marte.txt $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Mas a Múmia irá apreciar a falta de humidade. Como você pode adivinhar pelo verbo utilizado, git checkout checks out (i.e., restaura) uma versão anterior do arquivo. Nesse caso, estamos dizendo para o Git que queremos recuperar a versão do arquivo presente em HEAD, que corresponde a última versão salva. Se você você resolver resolver voltar para uma versão mais antiga você deve utilizar o identificado da respectiva versão: $ git checkout f22b25e marte.txt É importante lembrar que devemos utilizar o identificador da revisão anterior ao estado que desejamos desfazer. Um erro comum é utilizar o identificador da revisão na qual as alterações indesejadas foram feitas. No exemplo abaixo, queremos recuperar o estado anterior ao commit mais recente (HEAD~1), cuja identificação é f22b25e: O diagrama a seguir ilustra como o histórico de um arquivo deve ser (indo para antes de HEAD, a versão mais recente salva):

28 28 CAPÍTULO 5. EXPLORANDO O HISTÓRICO Figura 5.1: Git Checkout Figura 5.2: When Git Updates Revision Numbers

29 SIMPLIFICANDO O CASO COMUM 29 Simplificando o Caso Comum Se você tiver lido cuidadosamente a saída do comando git status você terá notado que ele encontra a seguinte dica: (use "git checkout -- <file>..." to discard changes in working directory) Como ela diz, git checkout irá restaurar os arquivos para o estado salvo em HEAD. O traço duplo, --, é necessário para separar o nome do arquivo a ser recuperado do comando propriamente dito: sem o traço duplo, Git tentará utilizar o nome do arquivo como o identificador da revisão. O fato de que os arquivos pode ser recuperados um por um tende a mudar a forma como as pessoas organizam seu trabalho. Se todo o trabalho consiste de um grande documento, será difícil (mas não impossível) de desfazer alguma mudança sem também desfazer outras, por exemplo desfazer as alterações na introdução sem também desfazer as alterações feitas na conclusão. Se a introdução e conclusão estiverem salvas em arquivos separados será muito mais fácil desfazer apenas as alterações em um dos arquivos. Recuperando versões antigas de um arquivo Jennifer fez alterações no seu script Python no qual ela estava trabalhando a duas semanas, e as alterações que ela fez essa manhã quebraram o script que não mais funciona. Ela já gastou em ~1h tentando corrigi-lo sem sucesso... Felizmente, ela esteve mantendo registro do seu trabalho utilizando Git! Qual comando a seguir permite ela recuperar a última versão salva do seu script Python chamado reducao-de-dados.py? 1. $ git checkout HEAD 2. $ git checkout HEAD reducao-de-dados.py 3. $ git checkout HEAD~1 reducao-de-dados.py 4. $ git checkout reducao-de-dados.py 5. 2 e 4

30 30 CAPÍTULO 5. EXPLORANDO O HISTÓRICO

31 Capítulo 6 Ignorando Arquivos Objetivos Configurar Git para ignorar arquivos específicos, e explicar porque isso é útil em alguns casos. Se tivermos arquivos que não desejamos serem monitorados pelo Git, por exemplo arquivos de backup criados pelo nosso editor ou arquivos intermediários criados durante a análise de dados. Vamos criar um exemplo bobo: $ mkdir resultados $ touch a.dat b.dat c.dat resultados/a.out resultados/b.out e verificar o que o Git diz: $ git status # On branch master # Untracked files: # (use "git add <file>..." to include in what will be committed) # # a.dat # b.dat # c.dat # resultados/ nothing added to commit but untracked files present (use "git add" to track) Colocando esses arquivos sob controle de versão é um desperdício de memória em disco. Algo pior é que ter eles listados toda vez pode reduzir nossa atenção para 31

32 32 CAPÍTULO 6. IGNORANDO ARQUIVOS as mudanças que realmente importam. Vamos então dizer para o Git ignorar alguns arquivos. Fazemos isso criando um arquivo denominado.gitignore no diretório raiz do nosso projeto. $ nano.gitignore $ cat.gitignore *.dat resultados/ A primeira expressão no arquivo.gitignore diz para o Git ignorar todos os arquivos que terminam com.dat e a segunda expressão para ele ignorar todos os arquivos dentro do diretório resultados. (Se algum desses arquivos já está sendo monitorado pelo Git ele continuará sendo-o). Uma vez que criamos esse arquivo, a saída do comando git status é muito mais limpa. $ git status # On branch master # Untracked files: # (use "git add <file>..." to include in what will be committed) # #.gitignore nothing added to commit but untracked files present (use "git add" to track) A única alteração que Git nota é a criação do arquivo.gitignore. Inicialmente você pode pensar que você não quer monitorar esse arquivo mas todas as pessoas que fizerem uso do repositório provavelmente irão querer ignorar os mesmos arquivos que ignoramos. Por esse motivo, vamos adicionar o arquivo.gitignore ao nosso controle de versão: $ git add.gitignore $ git commit -m "Adicionado gitignore" $ git status # On branch master nothing to commit, working directory clean Como um bônus, utilizar.gitignore irá ajudar nos a evitar de acidentadamente adicionar arquivos indesejados.

33 OBJETIVOS 33 $ git add a.dat The following paths are ignored by one of your.gitignore files: a.dat Use -f if you really want to add them. fatal: no files added Se realmente desejarmos desobedecer nossas configurações presentes no.gitignore precisamos informar isso ao Git utilizando git add -f. Também podemos verificar o status dos arquivos ignorados utilizando: $ git status --ignored # On branch master # Ignored files: # (use "git add -f <file>..." to include in what will be committed) # # a.dat # b.dat # c.dat # resultados/ nothing to commit, working directory clean

34 34 CAPÍTULO 6. IGNORANDO ARQUIVOS

35 Capítulo 7 Colaborando Objetivos Explicar o que são repositórios remotos e por que eles são úteis. Explicar o que acontece quando um repositório remoto é clonado. Explicar o que acontece quando mudanças são obtidas e enviadas para um repositório remoto. Controle de versão começa a fazer falta quando começamos a colaborar com outras pessoas. Já temos quase todas as ferramentas necessárias para fazer isso, só falta aprendermos como copiar alterações de um repositório para outro. Sistemas como Git permite trocar alterações entre dois repositórios quaisquer. Na prática, entretanto, é mais fácil utilizar uma cópia como hub central e mantêlo em um servidor conectado à internet do que no notebook de alguém. Grande parte dos programadores utilizam serviços de hospedagem como GitHub ou BitBucket para armazenar esses cópias. Vamos explorar os pros e os contras dessa abordagem no final dessa lição. Vamos começar por compartilhar as mudanças que fizemos no nosso projeto com o mundo. Autentique-se no GitHub e clique no ícone no canto superior direito para criar um novo repositório denominado planetas: Nomeie o seu repositório de planetas e selecione Create Repository : Assim que o repositório for criado, GitHub irá mostrar uma página com uma URL e algumas informações de como configurar seu repositório local: Esse procedimento realiza os seguintes comandos nos servidores do GitHub: $ mkdir planetas $ cd planetas $ git init 35

36 36 CAPÍTULO 7. COLABORANDO Figura 7.1: Criando um novo repositório no GitHub (Passo 1) Figura 7.2: Criando um novo repositório no GitHub (Passo 2)

37 HTTPS VS SSH 37 Figura 7.3: Criando um novo repositório no GitHub (Passo 3) Nosso repositório local ainda contem nosso trabalho anterior no arquivo marte.txt mas o repositório remoto no GitHub não contem nenhum arquivo: O próximo passo é conectar esses dois repositórios. Fazemos isso transformando o repositório no GitHub um repositório remote para o repositório local. Na página inicial do repositório no GitHub encontra-se a string necessária para identificá-lo: Selecione HTTPS para alterar o protocolo SSH para HTTPS. HTTPS vs SSH Utilizamos HTTPS porque ele não requer configurações adicionais. Depois do workshop você pode querer configurar acesso via SSH, que é um pouco seguro, seguindo um dos tutoriais disponibilizados por GitHub, Atlassian/BitBucket e GitLab (esse é um vídeo). Copie essa URL do navegador, vá para seu repositório local e execute o comando: $ git remote add origin Certifique-se de utilizar a URL do seu repositório ao invés da URL do Vlad: a única diferença deve ser seu nome de usuário no lugar de vlad. Você pode verificar que o comando anterior foi executado corretamente utilizando git remote -v:

38 38 CAPÍTULO 7. COLABORANDO Figura 7.4: Freshly-Made GitHub Repository Figura 7.5: Where to Find Repository URL on GitHub

39 PROXY 39 Figura 7.6: Changing the Repository URL on GitHub $ git remote -v origin origin (push) (fetch) O nome origin é o apelido local para seu repositório remoto: você pode utilizar outro apelido no lugar se você desejar, mas origin é a opção mais utilizada. Uma vez que o apelido origin está configurado, o comando a seguir irá copiar as alterações no repositório local para o repositório no GitHub: $ git push origin master Counting objects: 9, done. Delta compression using up to 4 threads. Compressing objects: 100% (6/6), done. Writing objects: 100% (9/9), 821 bytes, done. Total 9 (delta 2), reused 0 (delta 0) To * [new branch] master -> master Branch master set up to track remote branch master from origin. Proxy Se a rede que você está conectado utiliza um proxy existe uma change do último comando ter falhado com Could not resolve hostname

40 40 CAPÍTULO 7. COLABORANDO como mensagem de error. Para resolver esse problema você precisa informar ao Git sobre o proxy: $ git config --global http.proxy $ git config --global https.proxy Quando você se conectar em outra rede que não utiliza um proxy você terá que dizer para o Git desabilitar o uso do proxy utilizando $ git config --global --unset http.proxy $ git config --global --unset https.proxy Gerenciadores de Senhas Se seu sistema operacional possui um gerenciador de senha configurad, git push irá tentar utilizá-lo quando for necessário informar o usuário e senha. Se você desejar digitar seu usuário e senha no terminal ao invés do gerenciador de senha, digite $ unset SSH_ASKPASS Você talvez queira adicionar esse comando no final do seu ~/.bashrc para que esse passe a ser o comportamento padrão. Agora o seus repositórios locais e remotos estão no seguinte estado: A opção -u Normalmente você vai encontrar a opção -u em outras documentações disponíveis na internet. Ela está relacionada com conceitos apresentados na nossa lição intermediária e pode ser ignorada sem problemas. Você também pode pegar as alterações no seu repositório remoto para o local: $ git pull origin master From * branch master -> FETCH_HEAD Already up-to-date.

41 PRATICANDO SOZINHO 41 Figura 7.7: Repositório no GitHub após o primeiro push Nesse caso, nenhuma modificação foi recebida porque os dois repositórios já estavam sincronizados. Se alguém tivesse enviado alguma alteração para esse repositório no GitHub, o comando anterior teria baixado as modificações para o repositório local. Para o próximo passo, iremos trabalhar em pares. Escolha um dos seus repositórios no GitHub para utilizá-lo colaborativamente. Praticando sozinho Se você estiver seguindo essa lição sozinho, antes de continuar abra um segundo terminal, altere o diretório corrente para outro diretório (e.g. /tmp). Esse segundo terminal irá representar seu colega que estaria trabalhando em outro computador. Você não precisa dar permissões para ninguém pois o seu colega vai ser você mesmo. O dono do repositório que será utilizado precisa dar permissões de escrita para a outra pessoa. No GitHub, selecione Settings no lado direito, depois Collaborators e depois digite o usuário da sua dupla. Quem não é dono do repositório que será utilizado deve mudar de diretório, utilizando cd, de tal forma que ls não mais mostre o diretório planetas e em seguida criar uma cópia do repositório que será utilizado no seu computador: $ git clone

42 42 CAPÍTULO 7. COLABORANDO Figura 7.8: Adding collaborators on Github Troque vlad pelo usuário do seu parceiro (o dono do repositório que será utilizado). git clone irá criar uma cópia local do repositório remoto. Figura 7.9: After Creating Clone of Repository Agora o novo colaborador pode fazer uma alteração na sua cópia do repositório: $ cd planetas $ nano plutao.txt $ cat plutao.txt Também é um planeta! $ git add plutao.txt

43 MARCAÇÃO DE TEMPO NO GITHUB 43 $ git commit -m "Algumas notas sobre Plutão" 1 file changed, 1 insertion(+) create mode plutao.txt e depois enviar as mudanças para o GitHub: $ git push origin master Counting objects: 4, done. Delta compression using up to 4 threads. Compressing objects: 100% (2/2), done. Writing objects: 100% (3/3), 306 bytes, done. Total 3 (delta 0), reused 0 (delta 0) To da5..29aba7c master -> master Note que não precisamos criar um repositório remoto chamado origin pois Git faz isso automaticamente quando clonamos um repositório. (Por é o motivo que utilizamos origin anteriormente quando configuramos o repositório remoto manualmente). Podemos baixar as mudanças agora disponíveis no GitHub no repositório original em nossa máquina: $ git pull origin master remote: Counting objects: 4, done. remote: Compressing objects: 100% (2/2), done. remote: Total 3 (delta 0), reused 3 (delta 0) Unpacking objects: 100% (3/3), done. From * branch master -> FETCH_HEAD Updating 9272da5..29aba7c Fast-forward plutão.txt file changed, 1 insertion(+) create mode plutão.txt Marcação de tempo no GitHub Crie um repositório no GitHub, clone-o, adicione um arquivo, envie essa mudança para o GitHub e olhe o horário, em inglês timestamp, que as alterações foram feitas no GitHub. Como que o GitHub grava o tempo? E por que?

44 44 CAPÍTULO 7. COLABORANDO

45 Capítulo 8 Conflitos Objetivos Explicar o que são conflitos e quando eles ocorrem. Resolver conflitos ocorridos durante um merge. Logo que pessoas começam a trabalhar em paralelo alguém irá pisar no pé de outra pessoa. Isso também pode acontecer com uma única pessoa: se trabalharmos no mesmo arquivo do nosso notebook e do computador no laboratório, pode ser que façamos mudanças diferentes em cada uma das cópias. Controle de versão ajuda a gerenciarmos esses conflitos ao fornecer uma ferramenta para resolver a sobreposição de mudanças. Para que possamos aprender como resolver conflitos precisamos, primeiro, criar um. Atualmente o arquivo marte.txt corresponde, em todas as nossas cópias do repositório planeta, a $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Mas a Múmia irá apreciar a falta de humidade. Vamos adicionar uma linha na cópia no nosso diretório de usuário: $ nano marte.txt $ cat marte.txt 45

46 46 CAPÍTULO 8. CONFLITOS Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Mas a Múmia irá apreciar a falta de humidade. Linha adicionada na cópia do Lobisomem. e enviar essa mudança para o GitHub: $ git add marte.txt $ git commit -m "Adicionado linha em nossa cópia local" [master 5ae9631] Adicionado linha em nossa cópia local 1 file changed, 1 insertion(+) $ git push origin master Counting objects: 5, done. Delta compression using up to 4 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 352 bytes, done. Total 3 (delta 1), reused 0 (delta 0) To 29aba7c..dabb4c8 master -> master Agora vamos esperar nosso colaborador fazer uma alteração em sua cópia local sem atualizar a cópia local com as últimas alterações disponíveis no GitHub: $ nano marte.txt $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Mas a Múmia irá apreciar a falta de humidade. Adicionado linha diferente na outra cópia. Podemos salvar a alteração localmente: $ git add marte.txt $ git commit -m "Adicionado linha em minha cópia" [master 07ebc69] Adicionado linha em minha cópia 1 file changed, 1 insertion(+) mas o Git não irá deixar enviarmos nossas alterações para o GitHub:

47 OBJETIVOS 47 $ git push origin master To [rejected] master -> master (non-fast-forward) error: failed to push some refs to ' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Merge the remote changes (e.g. 'git pull') hint: before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details. Figura 8.1: The conflicting changes Git detecta que as alterações em uma cópia local sobrepõe aquelas feitas em outra cópia e previne de nós bagunçarmos nosso trabalho anterior. O que precisamos fazer é pegar as mudanças no GitHub, fazer um merge delas na cópia que estamos trabalhando atualmente e depois enviá-las novamente. Vamos começar por baixar as mudanças:

48 48 CAPÍTULO 8. CONFLITOS $ git pull origin master remote: Counting objects: 5, done. remote: Compressing objects: 100% (2/2), done. remote: Total 3 (delta 1), reused 3 (delta 1) Unpacking objects: 100% (3/3), done. From * branch master -> FETCH_HEAD Auto-merging marte.txt CONFLICT (content): Merge conflict in marte.txt Automatic merge failed; fix conflicts and then commit the result. git pull informa que existe um conflito e marca os conflitos nas linhas afetadas: $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Mas a Múmia irá apreciar a falta de humidade. <<<<<<< HEAD Linha adicionada na cópia do Lobisomem. ======= Adicionado linha diferente na outra cópia. >>>>>>> dabb4c8c450e8475aee9b14b4383acc99f42af1d Nossas mudanças aquelas em HEAD é precedido por <<<<<<<. Depois das nossas mudanças conflitantes, Git adiciona ======= como um separador das mudanças e maca o fim das alterações conflitantes baixadas do GitHub com >>>>>>>. (O conjunto de letras e dígitos depois desse marcador identifica a versão que acabamos de baixar.) Agora depende de nós editar o arquivo para remover os marcadores e reconciliar as alterações. Podemos fazer o que desejarmos: manter as alterações feitas nessa cópia, manter as alterações feitas na outra cópia, escrever algo novo para substituir ambas alterações ou removê-las. Vamos substituir ambas de modo que o arquivo fique como: $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Mas a Múmia irá apreciar a falta de humidade. Removemos o conflito nessa linha.

49 OBJETIVOS 49 Para finalizar o merge, nos adicionamos o arquivo marte.txt e criamos uma nova revisão: $ git add marte.txt $ git status # On branch master # All conflicts fixed but you are still merging. # (use "git commit" to conclude merge) # # Changes to be committed: # # modified: marte.txt # $ git commit -m "Juntando alterações provenientes do GitHub" [master 2abf2b1] Juntando alterações provenientes do GitHub Agora podemos enviar nossas alterações para o GitHub: $ git push origin master Counting objects: 10, done. Delta compression using up to 4 threads. Compressing objects: 100% (6/6), done. Writing objects: 100% (6/6), 697 bytes, done. Total 6 (delta 2), reused 0 (delta 0) To dabb4c8..2abf2b1 master -> master Git mantem o registro de quando realizamos um merge e desse modo não precisamos corrigir novamente esse conflito quando um colaborador baixar as novas mudanças: $ git pull origin master remote: Counting objects: 10, done. remote: Compressing objects: 100% (4/4), done. remote: Total 6 (delta 2), reused 6 (delta 2) Unpacking objects: 100% (6/6), done. From * branch master -> FETCH_HEAD

50 50 CAPÍTULO 8. CONFLITOS Updating dabb4c8..2abf2b1 Fast-forward marte.txt file changed, 1 insertion(+), 1 deletion(-) Como podemos verificar o arquivo marte.txt encontra na forma que salvamos após o merge: $ cat marte.txt Frio e seco, mas tudo é da minha cor favorita. Duas luas pode ser um problema para o Lobisomem. Mas a Múmia irá apreciar a falta de humidade. Removemos o conflito nessa linha. Não precisamos juntar as alterações novamente porque o Git sabe que alguém já fez isso. A habilidade de sistemas de controle de versão em resolver conflitos é uma das razões pela qual vários usuários tendem a dividir seus programas e artigos em vários arquivos ao invés de armazená-los em um único grande arquivo. Existe um outro benefício: quando conflitos em um arquivo ocorrem com frequência isso é uma indicação de que as responsabilidades não estão claras ou o trabalho precisa ser melhor dividido. Resolvendo conflitos que você criou 1. Clone o repositório criado pelo seu instrutor. 2. Adicione um novo arquivo nele e altere um arquivo existente (seu instrutor irá informar qual arquivo). 3. Quando requisitado pelo seu instrutor, baixe as mudanças do repositório para criar um conflito e resolva-o. Conflitos em arquivos que não são texto plano O que o Git faz quando existe um conflito em uma imagem ou em um arquivo não texto que está armazenado no controle de versão?

51 Capítulo 9 Ciência Aberta Objetivo Explicar como controle de versão pode ser útil como um caderno de anotações eletrônico para trabalhos computacionais. Explicar porque adicionar licença e informações de referência em um repositório de projeto é importante. Explicar quais opções de licença estão disponíveis e como escolher uma. Explicar como licenças e expectativas sociais diferem. O oposto de aberto não é fechado. quebrado. John Wilbanks (tradução literal) O oposto de aberto é O compartilhamento livre de informações deve ser o objetivo em ciência, mas a realidade é um pouco mais complicada. A prática padrão na atualidade parece algo como: Uma pesquisadora coleta alguns dados e armazena eles em uma máquina que ocasionalmente ganha uma cópia de backup por parte do departamento ao qual pertence. Ela então escreve ou modifica alguns pequenos programas (que também existe apenas na sua máquina) para analisar os dados. Uma vez que ela possua alguns resultados, ela escreve sobre eles e submete seu artigo. Ela talvez inclua seus dados um número crescente de jornais requer isso mas ela provavelmente não incluirá seus códigos. Algum tempo passa. 51

52 52 CAPÍTULO 9. CIÊNCIA ABERTA O jornal envia-lhe comentários anônimos de alguns outros pesquisadores do seu campo de pesquisa. Ela revisa seu paper para satisfazer os comentários feitos e reenvia o artigo, sendo que nesse meio tempo ela alterou os scripts. Mais tempo se passa. O artigo é eventualmente publicado. Ele talvez inclua um link para uma cópia online dos dados utilizados, mas o artigo em si estará atrás de uma subscrição paga: apenas pessoas que possuam uma assinatura pessoal ou institucional poderão ler o artigo. Entretanto, para um número crescente de pesquisadores, o processo parece mais com: Os dados coletados pela pesquisadora são armazenados em um repositório de acesso aberto como figshare ou Zenodo, logo que els são coletados e recebendo seu próprio DOI. Ou o dado já foi publicado e hospedado em Dryad. A pesquisadora cria um novo repositório no GitHub para guardar seu trabalho. Durante o processo de análise, ela envia as alterações feitas em seus scripts (e possivelmente os arquivos de saída) para o repositório no GitHub. Ela também utiliza o repositório para seu artigo sendo que o repositório funciona como um hub para a colaboração com seus colegas. Quando ela está satisfeita com o estado do seu artigo, ela disponibiliza uma versão no arxiv ou em outro servidor de preprints e convida outros colegas para comentarem o trabalho. Baseado nesses comentários, ela provavelmente disponibiliza várias outras versões antes de finalmente submeter seu artigo ao jornal. O artigo publicado inclui links para o preprint, para seu código e para os dados de modo que será muito mais fácil para outros pesquisadores utilizar seu trabalho como ponto de partida para suas próprias pesquisas. Esse modelo aberto acelera descobertas: quanto mais aberto o trabalho é, mais citado e reutilizado ele é. Entretanto, pessoas que querem trabalhar dessa forma precisam tomar algumas decisões sobre o que exatamente aberto significa na prática. Controle de versão de cadernos de anotações científicos eletrônicos O benefício do controle de versão é, essencialmente, que quando utilizado adequadamente, você pode utilizar o controle de versão como uma forma de cadernos de anotações científicos eletrônicos para seu trabalho computacional.

53 LICENCIAMENTO 53 O estágio conceitual do seu trabalho está documentado, incluindo quem fez o que e quando. Todo passo está associado a um identificador único (o ID do commit) para a maior parte das intenções e usos. Você pode amarrar documentação de motivações, ideias e outros trabalhos intelectuais diretamente às alterações relacionadas. Você pode referir ao que utilizou na sua pesquisa para obter o resultado computacional de uma forma que é única e recuperável. Com um sistema de controle distribuído como o Git, o repositório de controle de versão é facilmente arquivado para a posterioridade, e contem o histórico completo. Licenciamento Quando um repositório contendo código fonte, manuscritos ou outro trabalho criativo torna-se público ele deve incluir um arquivo LICENSE ou LICENSE.md ou LICENSE.md na base do diretório correspondente ao repositório que expresse claramente sob qual licença o conteúdo daquele repositório está disponível. Isso é necessário porque trabalhos criativos, isso inclui códigos fontes, encontram-se automaticamente sob a lei de proteção à propriedade intelectual (mais expecificamente do copyright). Códigos fontes que parecem ser ou são expressamente divulgados como livremente acessível não abdicou de tal proteção. Desta forma, aqueles que (re)utilizam código fonte que não possui expresso uma licença fazem isso à sua própria sorte porque os autores de tal código fonte sempre podem, unilateralmente, fazer com que o (re)uso seja ilegal. Uma licença resolve esse problema ao oferecer direitos a outros que não teriam de outra forma. Os direitos são oferecidos sob algumas condições que algumas vezes são um pouco diferente de uma licença para outra. Em contrates com licenças proprietárias, licenças abertas certificadas pela Open Source Initiative oferecem, pelo menos, os seguintes direitos, referenciados à Open Source Definition: 1. O código fonte está disponível, e pode ser utilizado e redistribuído sem restrições, incluindo como parte de uma coleção. 2. Modificações ou trabalhos derivados são permitidos, e a distribuição destes é permitida. 3. A questão de quem recebe esses direitos não está sujeita à discriminação, incluindo pelo tipo de uso como comercial versus acadêmico. Como escolher a licença mais adequada pode parecer um problema, dado que existem várias licenças. Na prática, algumas poucas licenças são populares, dentre as quais: Licença Pública Geral GNU (GPL),

54 54 CAPÍTULO 9. CIÊNCIA ABERTA Licença MIT, Licença BSD. A GPL difere da maior parte das outras licenças de código aberto pois ela é viral: alguém que distribui um código baseado em um código GPL, ou que inclui código GPL, deve fazê-lo licenciando sob a GPL. O artigo a seguir oferece uma excelente visão geral sobre licenças e opções de licenças da perspectiva de um cientista que também escreve código: Morin, A., Urban, J., and Sliz, P. A Quick Guide to Software Licensing for the Scientist-Programmer PLoS Computational Biology 8(7) (2012): e No fim do dia o que importa é que exista uma declaração clara de qual a licença utilizada, e que essa licença seja uma já verificada e aprovada pela OSI. Além disso, é melhor escolher a licença no início do projeto, mesmo que o repositório ainda não seja público. Postergar a escolha de uma licença apenas torna as coisas mais complicadas depois, pois cada vez que um novo colaborador começa a contribuir, ele, também, possui direitos autorais e precisará ser consultado e concordar com uma mudança na licença. Licenciamento de produtos que não são programas de computador Se o conteúdo de um repositório possui resultado de uma pesquisa que não seja programas de computador, tais como dados, e/ou texto (manuais, relatórios técnicos, manuscritos), a maioria das licenças voltadas para programas de computador não são compatíveis. Data: Na maioria das juridições a maior parte dos dados (possivelmente com exceção de fotos, imagens médicas, etc) são considerados fatos da natureza, e por esse motivo não são passíveis de proteção pelo direito autoral. Entretando, utilizando uma licença, que por definição atribui direito autoral, para indicar expectativa social e acadêmica por atribuição serve apenas para criar uma situação legal sombrio. É melhor deixar claro a situação legal utilizando uma licença de domínio público como a Creative Commons Zero (CC0), e as expectativas sociais com pedidos expressões de como utilizar e citar os dados. O repositório de dados Dryad requer isso. Trabalhos criativos: Manuais, relatórios, manuscritos e outros trabalhos criativos são passíveis de proteção pelo direito autoral e acabam automaticamente protegidos pelo copyright, da mesma forma que código fonte de programa de computador. Creative Commons preparou um conjunto de licenças utilizando uma combinação de quatro restrições:

55 HOSPEDAGEM 55 Atribuição: trabalhos derivados devem dar créditos ao autor original pelo seu trabalho. Não Derivado: pessoas podem copiar o trabalho mas precisam transmiti-lo sem modificações. Compartilha Igual: trabalhos derivados precisam ser licenciados sob os mesmos termos do trabalho original. Não Comercial: uso sem fins comerciais é permitido, mas uso comercial não. Apenas a Atribuição (CC-BY) e Compartilha Igual (CC-BY-SA) são licensas consideradas Open. Software Carpentry utiliza CC-BY para suas lições e a licença MIT para os códigos com o objetivo de encorajar os mais variados reusos. Novamente, o mais importante no arquivo LICENSE na raiz do seu projeto é declarar de forma clara a licença utilizada. Você também deveria incluir um arquivo CITATION ou CITATION.txt que descreva como referenciar seu projeto. O arquivo CITATION utilizado por Software Carpentry contem: To reference Software Carpentry in publications, please cite both of the following: Greg Wilson: "Software Carpentry: Lessons Learned". arxiv: , July author = {Greg Wilson}, title = {Software Carpentry: Lessons Learned}, version = {1}, date = { }, eprinttype = {arxiv}, eprint = { } } Hospedagem A segunda grande pergunta para equipes que desejam abrir seu trabalho é onde hospedar seus códigos e dados. Uma opção é o laboratório, o departamento ou a universidade providenciar um servidor, gerenciar contas, cópias de segurança,... O benefício dessa abordagem é que deixa claro quem é dono do que, o que é particularmente importante se algum dos materiais é sensível (i.e., relacionado com experimentos envolvendo experimentos em seres humanos ou que serão utilizados para na aplicação por uma patente). O lado negativo dessa abordagem é o custo de manter o serviço e sua longevidade: um pesquisador que passou os últimos dez anos coletando dados deseja ter certeza que os dados coletados irão

56 56 CAPÍTULO 9. CIÊNCIA ABERTA estar disponíveis pelos próximos dez anos mas, infelizmente, os financiamentos para infraestruturas acadêmicas não duram mais que alguns anos. Outra opção é comprar um domínio e pagar um Internet service provider (ISP) para hospedar o conteúdo. Essa abordagem permite maior controle por parte do indivíduo e do grupo mas pode criar problemas quando mudando de instituição e necessitará de mais tempo e esforço do que as outras opções listadas nessa página. A terceira opção é utilizar um serviço de hospedagem gratuito como GitHub, BitBucket, ou SourceForge. Todos esses serviços oferecem uma interface web que possibilita as pessoas criarem, visualizarem e editarem seus repositórios. Esses serviços também oferecem ferramentas para comunicação e gerenciamento do projeto que incluem lista de problemas, wiki, notificação por e revisão de código. Esses serviços se beneficiam da economia de escala e efeito de rede: é mais fácil manter funcionando um grande serviço do que vários pequenos serviços nos mesmos padrões. Além disso é mais fácil para pessoas colaborarem se estiverem utilizando o mesmo serviço: utilizar um serviço popular pode ajudar a conectar seu projeto com comunidades que já utilizam o mesmo serviço. Como um exemplo, a Fundação Software Carpentry utiliza o GitHub para hospedagem de seus projetos que inclui essa lição. Qualquer pessoa com uma conta no GitHub pode sugerir mudanças nesse texto. Posso utilizar uma licença aberta? Compartilhar é o desejável para a ciência mas muitas instituições podem impedir seus pesquisadores de fazer, por exemplo porque quererem se proteger para futuras aplicações de patentes. Se você deparar-se com tais restrições, pode ser produtivo você perguntar sobre as motivações para as restrições - tanto como primeiro passo para pedir uma exceção para um projeto específico como também para tentar uma reforma mais ampla no nível institucional na direção da ciência aberta. Posso utilizar uma licença aberta? Encontre em que parte do seu trabalho você pode aplicar uma licença de código aberta. Você pode fazer isso unilateralmente ou você precisa da permissão de alguém na sua instituição? Se precisa de permissão, quem é essa pessoa? Meu trabalho pode ser público? Descubra se você pode hospedar seu trabalho em um serviço gratuito. Você pode fazer isso unilateralmente ou você precisa da permissão

57 MEU TRABALHO PODE SER PÚBLICO? 57 de alguém na sua instituição? Se precisa de permissão, quem é essa pessoa?

58 58 CAPÍTULO 9. CIÊNCIA ABERTA

59 Capítulo 10 Motivação Por que utilizar Controle de Versão? Deixar que um programa lide com o controle de versão do seu projeto permite que você foque-se no seu projeto. Por que Git? Porque muitas pessoas estão utilizando o GitHub para colaborar. Próximos Passos Vamos começar! 59

60 60 CAPÍTULO 10. MOTIVAÇÃO

61 Capítulo 11 Referência Configurando o Git Usar git config para configurar o nome de usuário, endereço de , editor e outras preferências em uma máquina. Criando um repositório git init inicializa um repositório. Monitorando alterações git status mostra o estado de um repositório. Arquivos podem ser armazenados no diretório de trabalho do projeto (que o usuário visualiza), na área intermediária (onde a próxima versão está sendo construída) e no repositório local (onde snapshots são salvos permanentemente). git add move os arquivos para a área temporária. git commit cria um novo snapshot da área temporária no repositório local. Sempre escreva uma mensagem descritiva quando criar uma nova revisão. Explorando o histórico git diff mostra a diferença entre revisões. git checkout recupera uma versão anterior. 61

62 62 CAPÍTULO 11. REFERÊNCIA Ignorando Arquivos O arquivo.gitignore informa o Git quais arquivos devem ser ignorados. Colaborando Um repositório Git local pode ser conectado com um ou mais repositórios remotos. Utilize o protocolo HTTPS para comunicar-se com um repositório remoto até que você aprenda como configurar autenticação via SSH. git push copia as mudanças de um repositório local para um repositório remoto. git pull copia as mudanças de um repositório remoto para um repositório local. git clone copia um repositório remoto para criar um repositório local que possui um repositório remoto chamado de origin automaticamente configurado. Conflitos Conflitos ocorrem quando duas ou mais pessoas alteram o mesmo arquivo ao mesmo tempo. Um sistema de controle de versão não deixa um usuário sobre-escrever as alterações de um outro usuário cegamente. Ao contrário, ele destaca os conflitos para que estes possam ser resolvidos. Ciência Aberta Trabalhos científicos são mais úteis e mais citados que trabalhos científicos fechados. Pessoas que incorporam software GPL em seus softwares devem torná-los abertos utilizando a GPL; a maioria das outras licenças não requer isso. A família de licenças Creative Commons permite que pessoas misturem requerimentos e restrições de atribuição, criação de trabalhos derivados, compartilhamento, e comercialização. Pessoas que não são advogados não devem tentar escrever licenças começando do zero. Projetos podem ser hospedados nos servidores da universidade, em um domínio pessoal, ou em repositórios públicos.

63 GLOSSÁRIO 63 Regras relacionadas com a propriedade intelectual e armazenamento de informações sensíveis são válidas independentemente de onde o código e o dado são hospedados. Glossário conjunto de alterações Um grupo de alterações em um ou mais arquivos que são salvos em um repositório sob controle de versão em uma única operação. commit Ação de salvar o estado atual de um conjunto de arquivos (um conjunto de alterações) em um repositório sob controle de versão. Se um commit contem mudanças em vários arquivos, todas as alterações são salvas em conjunto. conflito Uma alteração feita por um usuário do sistema de controle de versão que é incompatível com as alterações feitas por outros usuários. Auxiliar usuários a resolver conflitos é uma das maiores tarefas de um sistema de controle de versão. HTTP O Protocolo Hypertext Transfer usado para compartilhar páginas da internet e outros dados na World Wide Web. licenças infecciosas Uma licença como a GPL que obriga as pessoas que incorporam material sob essa licença em seu trabalho a utilizar a mesma licença ou uma com requerimentos similares. merge (um repositório): Reconciliar dois conjuntos de alterações em um repositório. protocolo Um conjunto de regras que definem como um computador se comunica com outro. Protocolos populares na Internet incluem HTTP e SSH. remoto Um repositório sob controle de versão que não o atual que de alguma forma é um espelho ou está conectado com o atual. repositório Uma área de armazenamento onde um sistema de controle de versão armazena revisões anteriores dos arquivos e informações sobre quem, quando e onde criou uma nova revisão. resolver Eliminar os conflitos entre duas ou mais alterações incompatíveis em um arquivo ou um conjunto de arquivos que estão sendo gerenciados por um sistema de controle de versão. revisão Um registro do estado de um repositório de controle de versão. SSH O protocolo Secure Shell utilizado para a comunicação segura entre computadores. timestamp O registro de quando um evento em particular ocorreu. controle de versão Uma ferramenta para gerenciar alterações em um conjunto de arquivos. Cada conjunto de mudanças cria uma nova revisão dos arquivos; o sistema de controle de versão permite os usuários recuperarem versões anteriores de forma segura, e ajuda a gerenciar conflitos entre

64 64 CAPÍTULO 11. REFERÊNCIA alterações feitas por diferente usuários.

65 Capítulo 12 Discussão Frequently Asked Questions People often have questions about Git beyond the scope of the core material. Students who have completed the rest of the lessons might find value in looking through the following topics. Note that since this material isn t essential for basic Git usage, it won t be covered by the instructor. More Advanced Git Configuration In Setting Up Git, we used git config --global to set some default options for Git. It turns out that these configuration options get stored in your home directory in a plain text file called.gitconfig. $ cat ~/.gitconfig [user] name = Vlad Dracula = [email protected] [color] ui = true [core] editor = nano This file can be opened in your preferred text editor. (Note that it is recommended to continue using the git config command, as this helps avoid introducing syntax errors.) 65

66 66 CAPÍTULO 12. DISCUSSÃO Eventually, you will want to start customizing Git s behaviour. This can be done by adding more entries to your.gitconfig. The available options are described in the manual: $ git config --help In particular, you might find it useful to add aliases. These are like shortcuts for longer git commands. For example, if you get sick of typing git checkout all the time, you could run the command: $ git config --global alias.co checkout Now if we return to the example from Exploring History where we ran: $ git checkout f22b25e mars.txt we could now instead type: $ git co f22b25e mars.txt Styling Git s Log A good target for customization is output from the log. The default log is quite verbose but gives no graphical hints such as information about which commits were done locally and which were pulled from remotes. Use git log --help and git config --help to look for different ways to change the log output. How do you expect the log to look after running the following commands? $ git config --global alias.lg "log --graph" $ git config --global log.abbrevcommit true $ git config --global format.pretty oneline $ git lg You can try the commands out and if you decide you don t like the effect, you can get rid of them by running: $ git config --global --unset alias.lg $ git config --global --unset log.abbrevcommit $ git config --global --unset format.pretty

67 VERSION CONTROLLING THE GITCONFIG 67 Version Controlling the Gitconfig In the previous challenge, we suggested using the --unset flag to delete unwanted options from.gitconfig. Another way to roll back changes is to version control your.gitconfig using Git. Go to GitHub and do a search for gitconfig. You will hopefully see hundreds of repositories in which people have stored their own Git configuration files. Sort them by most number of stars and have a look at the top few. Do you see any ideas for things you might want to try out in your own.gitconfig? (Remember to check that they re using an open source license before you clone their work for your own use.) Non-text Files Recall when we discussed Conflicts there was a challenge that asked: What does Git do when there is a conflict in an image or some other non-textual file that is stored in version control? We will now revisit this in more detail. Many people want to version control non-text files, such as images, PDFs and Microsoft Office or LibreOffice documents. It is true that Git can handle these filetypes (which fall under the banner of binary file types). However, just because it can be done doesn t mean it should be done. Much of Git s magic comes from being able to do line-by-line comparisons ( diffs ) between files. This is generally easy for programming source code and marked up text. For non-text files, a diff can usually only detect that the files have changed but can t say how or where. This has various impacts on Git s performance and will make it difficult to compare different versions of your project. For a basic example to show the difference it makes, we re going to go see what would have happened if Dracula had tried using outputs from a word processor instead of plain text. Create a new directory and go into it: $ mkdir planets-nontext $ cd planets-nontext Use a program such as Microsoft Word or LibreOffice Writer to create a new document. Enter the same text that we began with before:

68 68 CAPÍTULO 12. DISCUSSÃO Cold and dry, but everything is my favorite color Save the document into the planets-nontext directory with the name of mars.doc. Back in the terminal, run the usual commands for setting up a new Git repository: $ git init $ git add mars.doc $ git commit -m "Starting to think about Mars" Then make the same changes to mars.doc that we (or Vlad) previously made to mars.txt. Cold and dry, but everything is my favorite color The two moons may be a problem for Wolfman Save and close the word processor. Now see what Git thinks of your changes: $ git diff diff --git a/mars.doc b/mars.doc index 53a66fd..6e988e Binary files a/mars.doc and b/mars.doc differ Compare this to the earlier git diff obtained when using text files: diff --git a/mars.txt b/mars.txt index df0654a..315bf3a a/mars.txt Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman Notice how plain text files give a much more informative diff. You can see exactly which lines changed and what the changes were. An uninformative git diff is not the only consequence of using Git on binary files. However, most of the other problems boil down to whether or not a good diff is possible. This isn t to say you should never use Git on binary files. A rule of thumb is that it s okay if the binary file won t change very often, and if it does change, you don t care about merging in small differences between versions.

69 NON-TEXT VERSION CONTROL 69 We ve already seen how a word processed report will fail this test. An example that passes the test is a logo for your organization or project. Even though a logo will be stored in a binary format such as jpg or png, you can expect it will remain fairly static through the lifetime of your repository. On the rare occasion that branding does change, you will probably just want to replace the logo completely rather than merge little differences in. Non-text Version Control How would you write a program to diff non-text files? If you go through two files byte by byte, it might be easy to find the first place where differences begin. However, what if two stretches in the middle of a file are exactly the same but have different start locations? Or if a stretch of bytes in one file is identical to two different stretches in the other file, which should be privileged as the matching part? Try Googling for phrases such as non-text diff and binary version control to see what ideas and solutions other people have come up with. (You might also see some more arguments about why you shouldn t use binary files with Git.)

70 70 CAPÍTULO 12. DISCUSSÃO

71 Capítulo 13 Guia para Instrutores Legend Overall Version control might be the most important topic we teach, but Git is definitely the most complicated tool. However, GitHub presently dominates the open software repository landscape, so we have to help novices learn just enough Git to feel they can and should learn more on their own. This is why we don t teach branching: while it is a power tool in the hands of a knowledgeable user, it is an extra cognitive burden for someone who is new to the idea of version control. This is also why we don t get into hashes and commit objects with novices, but try instead to convince them that version control is: 1. a better backup system; 2. a better Dropbox; and 3. a better way to collaborate than mailing files back and forth. We close with material on licensing because: 1. questions about who owns what, or can use what, arise naturally once we start talking about using public services like GitHub to store files; and 2. the discussion gives learners a chance to catch their breath after what is often a frustrating couple of hours. 71

72 72 CAPÍTULO 13. GUIA PARA INSTRUTORES Teaching Notes Try to make it clear that Git and GitHub are not the same thing: Git is an open source version control tool, GitHub is a company that s built a really useful website on top of it. Ask, Who uses undo in their editor? They say, Undo is the simplest form of version control. Decide in advance whether all the learners will work in one shared repository, or whether they will work in pairs (or other small groups) in separate repositories. The former is easier to set up; the latter runs more smoothly. Make sure the network is working before starting this lesson. Give learners a five-minute overview of what version control does for them before diving into the watch-and-do practicals. Most of them will have tried to co-author papers by ing files back and forth, or will have biked into the office only to realize that the USB key with last night s work is still on the kitchen table. Instructors can also make jokes about directories with names like final version, final version revised, final version with reviewer three s corrections, really final version, and, come on this really has to be the last version to motivate version control as a better way to collaborate and as a better way to back work up. Version control is usually not the first subject in a workshop, so get learners to create a GitHub account after the session before. When giving instructions, be very clear which files learners are to edit: it is common for them to (for example) edit the instructor s biography rather than their own, or to use the instructor s user ID when committing. Be equally clear when they are to edit things: it s also common for someone to edit the file the instructor is editing and commit changes while the instructor is explaining what s going on, so that a conflict occurs when the instructor comes to commit the file. If some learners are using Windows, there will inevitably be issues merging files with different line endings. (Even if everyone s on some flavor of Unix, different editors may or may not add a newline to the last line of a file.) Take a moment to explain these issues, since learners will almost certainly trip over them again. We don t use a Git GUI in these notes because we haven t found one that installs easily and runs reliably on the three major operating systems, and because we want learners to understand what commands are being run. That said, instructors should demo a GUI on their desktop at some point during this lesson and point learners at this page.

73 SETTING UP GIT 73 Instructors should show learners graphical diff/merge tools like DiffMerge. When appropriate, explain that we teach Git rather than CVS, Subversion, or Mercurial primarily because of GitHub s growing popularity: CVS and Subversion are now seen as legacy systems, and Mercurial isn t nearly as widely used in the sciences right now. Setting Up Git We suggest instructors and students use nano as the text editor for this lessons because: it runs in all three major operating systems, it runs inside the shell (switching windows can be confusing to students), and it has shortcut help at the bottom of the window. Please point out to students during setup that they can and should use another text editor if they re already familiar with it. Below you will find some tips that could help solving problems when using other editors. Creating a Repository The challenge Places to create repositories tries to reinforce the idea that the.git folder contains the whole Git repo and deleting this folder undoes a git init. It also gives the learner the way to fix the common mistake of putting unwanted folders (like Desktop) under version control. Instead of removing the.git folder directly, you can choose to move it first to a safer directory and remove it from there: mv.git temp_git rm -rf temp_git Tracking Changes Exploring History One thing that has caused confusion comes up when recovering old versions towards the end of Exploring history. If, instead of doing $ git

74 74 CAPÍTULO 13. GUIA PARA INSTRUTORES checkout f22b25e mars.txt, someone does $ git checkout f22b25e, they wind up in the detached HEAD state and confusion abounds. It s then possible to keep on committing, but things like git push origin master a bit later will not give easily comprehensible results. It also makes it look like commits can be lost. Ignoring Things Collaborating If your learners are advanced enough to be comfortable with SSH, tell them they can use keys to authenticate on GitHub instead of passwords, but don t try to set this up during class: it takes too long, and is a distraction from the core ideas of the lesson. Role playing between two instructors can be effective when teaching the collaboration and conflict sections of the lesson. One instructor can play the role of the repository owner, while the second instructor can play the role of the collaborator. If it is possible, try to use two projectors so that the computer screens of both instructors can be seen. This makes for a very clear illustration to the students as to who does what. It is also effective to pair up students during this lesson and assign one member of the pair to take the role of the owner and the other the role of the collaborator. In this setup, challenges can include asking the collaborator to make a change, commit it, and push the change to the remote repository so that the owner can then retreive it, and vice-versa. The role playing between the instructors can get a bit dramatic in the conflicts part of the lesson if the instructors want to inject some humor into the room. If you don t have two projectors, have two instructors at the front of the room. Each instructor does their piece of the collaboration demonstration on their own computer and then passes the projector cord back and forth with the other instructor when it s time for them to do the other part of the collaborative workflow. It takes less than 10 seconds for each switchover, so it doesn t interrupt the flow of the lesson. And of course it helps to give each of the instructors a different-colored hat, or put different-colored sticky notes on their foreheads. Conflicts Open Science

75 Capítulo 14 Licença Material Todo o material da Software Carpentry é disponibilizado sob a licença Creative Commons Atribuição 4.0 Internacional. A seguir encontra-se um sumário do texto legal completo da licença Creative Commons Atribuição 4.0 Internacional e não é um substituto para esse. Você é livre para: Compartilhar copiar e redistribuir o material em qualquer mídia ou formato Adaptar remixar, transformar, e criar a partir do material para qualquer fim, mesmo que comercial. O licenciante não pode revogar estes direitos desde que você respeite os seguintes termos: Atribuição Você deve dar crédito (mencionando que seu trabalho é derivado de um trabalho cujos direitos são da Software Carpentry e, quando possível, incluir um link para incluir um link para a licença utilizada, e indicar se alterações foram feitas. Você pode fazê-lo de qualquer maneira razoável, mas de nenhuma maneira que sugira o licenciante aprove seu uso. Sem restrições adicionais Você não pode aplicar termos jurídicos ou medidas de caráter tecnológico que restrinjam legalmente outros de fazerem algo que a licença permita. Avisos: 75

76 76 CAPÍTULO 14. LICENÇA Você não tem de cumprir com os termos da licença relativamente a elementos do material que estejam no domínio público ou cuja utilização seja permitida por uma exceção ou limitação que seja aplicável. Não são dadas quaisquer garantias. A licença pode não lhe dar todas as autorizações necessárias para o uso pretendido. Por exemplo, outros direitos, tais como direitos de imagem, de privacidade ou direitos morais, podem limitar o uso do material. Software Exceto onde indicado o contrário, exemplos de programas e outros softwares fornecidos pela Software Carpentry são disponibilizados sob a licença MIT. que é aprovada pela OSI. A permissão é concedida, a título gratuito, para qualquer pessoa que obtenha uma cópia deste software e arquivos de documentação associados (o Software ), para lidar com o Software sem restrição, incluindo, sem limitação dos direitos de uso, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e / ou vender cópias do Software, e para permitir que as pessoas às quais o Software é fornecido a fazê-lo, mediante as seguintes condições: O aviso de direito autoral acima e este aviso de permissão devem ser incluídos em todas as cópias ou partes substanciais do Software. O Software é fornecido como está, sem qualquer tipo de garantia, expressa ou implícita, incluindo mas não se limitando a garantias de comerciabilidade, adequação a uma finalidade específica e não violação. Em nenhum caso os autores ou os detentores dos direitos autorais se responsabilizarão por qualquer reclamação, danos ou qualquer outra responsabilidade, seja em razão de contrato, ato ilícito ou de outra forma, resultantes de ou em conexão com o software ou a utilização ou outras negociações no Software. Trademark Software Carpentry e o logo Software Carpentry são marcas registradas trademarks de NumFOCUS.