github
2.3.0
Citação : Haghish, EF (2020). Desenvolver, manter e hospedar software estatístico Stata no GitHub. O Jornal Stata, 20(4), 931-951.
github é um módulo Stata para pesquisar e instalar pacotes Stata do GitHub, incluindo versões anteriores de um pacote. É uma combinação de vários comandos Stata, como search , findit e ssc , mas, em vez disso, é feito para gerenciar pacotes Stata hospedados no GitHub. Além disso, o pacote fornece novos recursos para controle de versão que não estão disponíveis para usuários do Stata em outros lugares (por exemplo, o pacote permite instalar versões mais antigas de um pacote Stata para reproduzir uma análise realizada com software mais antigo).
NOTÍCIAS : Apresentando o comando gitget . gitget simplifica ainda mais a instalação e atualização de um pacote. ele fornece um banco de dados para todos os pacotes Stata existentes no GitHub, o que permite instalar um pacote que está hospedado no GitHub - e é conhecido por gitget , bastando digitar:
gitget packagename
O comando gitget depende de uma lista completa de pacotes Stata no GitHub para identificar a URL de um projeto. Esta lista é criada programaticamente usando um programa de pesquisa que detecta pacotes Stata. Primeiro, todos os repositórios Stata são identificados e armazenados em repolist.dta . A seguir, os pacotes instaláveis são extraídos e armazenados em gitget.dta que também é instalado com o pacote em sua máquina. A lista completa do arquivo também está disponível para visualização neste repositório
Índice
gitget Nos últimos anos, os usuários do Stata têm usado cada vez mais o GitHub para compartilhar códigos e conjuntos de dados do Stata, desenvolver software estatístico e hospedar pacotes do Stata, conforme mostrado na figura abaixo. Esta é realmente uma boa notícia para a comunidade Stata e para qualquer pessoa que promova a transparência da pesquisa! O módulo github facilita a pesquisa, instalação, gerenciamento e até mesmo a construção de pacotes Stata. Além disso, permite instalar versões de desenvolvimento ou, alternativamente, versões estáveis de um pacote. Também permite especificar dependências de pacotes que serão instaladas automaticamente, tornando o GitHub ainda mais atraente para usuários e desenvolvedores do Stata. Aqui, mostro rapidamente como instalar e usar o pacote github .
github Você pode instalar a versão mais recente do comando github executando o seguinte código:
net install github, from("https://haghish.github.io/github/")
A sintaxe geral do pacote pode ser resumida como:
github [subcommand] [...]
Onde o [ subcomando ] pode ser:
| Subcomando | Descrição |
|---|---|
search | encontra um pacote Stata no GitHub |
findfile | procura um arquivo entre todos os pacotes Stata no GitHub |
install | instala um pacote do GitHub |
list | fornece informações sobre pacotes instalados com github |
query | lista todas as versões anteriores de um pacote |
check | testa se um repositório é instalável |
uninstall | remove um pacote do Stata |
update | atualiza um pacote do GitHub |
version | retorna a versão de um pacote instalado |
e o [ ... ] pode ser nome de usuário/repositório ou nome do pacote com base no subcomando especificado.
Para instalar um pacote, tudo que você precisa é o nome de usuário do GitHub e o nome do repositório. A combinação de nome de usuário e nome do repositório - separados por uma barra - fornece a URL necessária para o repositório. Por exemplo, para instalar o pacote MarkDoc, que está hospedado em https://github.com/haghish/markdoc, basta digitar:
github install haghish/markdoc [, stable version("")]
O pacote github inclui um banco de dados para a lista completa de pacotes Stata hospedados no GitHub. Portanto, você também pode instalar um pacote apenas especificando o nome do pacote. O comando gitget - que é um wrapper para github install - pode instalar ou atualizar pacotes Stata do GitHub apenas perguntando o nome do pacote:
gitget packagename [, stable version("")]
Por exemplo, se você deseja instalar o pacote markdoc , digitar gitget markdoc seria tão bom quanto digitar github install haghish/markdoc . Se você deseja inspecionar a lista de pacotes Stata hospedados no GitHub, consulte o conjunto de dados gitget.dta .
| Opções | Descrição |
|---|---|
stable | instala a última versão estável do pacote |
version(str) | instala a versão de lançamento especificada |
Você pode pesquisar o pacote Stata no GitHub usando uma palavra-chave ou várias palavras-chave. Isso é semelhante aos comandos search ou findit do Stata, mas em vez disso, usado apenas para pesquisar pacotes GitHub:
github search weaver
Pesquisar a API do GitHub de forma eficaz é muito importante. Para isso, o pacote inclui uma GUI de pesquisa que mostra a sintaxe que você pode usar para restringir sua pesquisa ou expandi-la para incluir outras fontes. O comando search também analisa as datas de lançamento dos pacotes hospedados no comando net , o que é um recurso muito útil. Para iniciar a GUI, digite:
db github
Por exemplo, se você usar o comando github search para pesquisar o pacote markdoc , obterá a seguinte saída:
github possui um banco de dados integrado que rastreia os pacotes instalados em sua máquina e, claro, também informa as versões dos pacotes instalados na máquina. A versão é obtida das tags de lançamento exclusivas do pacote, especificadas pelo desenvolvedor. Você pode list os pacotes instalados e obter informações úteis sobre eles. Este comando também notifica se houver uma atualização disponível para algum dos seus pacotes GitHub . Por exemplo, no resultado abaixo, sabemos que existem atualizações disponíveis para dois de nossos pacotes. também podemos clicar no link (update) para atualizar o pacote para a versão mais recente.
. github list
Nem todos os pacotes são instaláveis. Os repositórios Stata devem ter arquivos toc e pkg para serem instaláveis. Você pode verificar se um pacote é instalável ou não usando o subcomando check .
github check haghish/markdoc
Este é um ponto bastante importante a se prestar atenção porque o comando
github searchque é usado para pesquisar pacotes Stata no GitHub tende a descartar repositórios Stata que não são instaláveis. Em outras palavras, se o seu repositório não incluir esses arquivos, ele não será considerado um pacote Stata, a menos que você especifique a opçãoallem sua pesquisa (na GUI de pesquisa, marque a opção mostrar repositórios GitHub que não são instaláveis ). No entanto, o pacotegithubtambém inclui uma GUI para construir esses arquivos. Usando a GUI que vem comgithub, você pode criar facilmente esses arquivos para o seu repositório (veja abaixo).
Para instalar um pacote, use o subcomando uninstall , seguido do nome do pacote. Por exemplo:
github uninstall markdoc
GitHub permite arquivar um número ilimitado de versões de pacotes. O comando github possui uma opção para especificar a versão do pacote, permitindo a instalação de versões anteriores do pacote. Por exemplo, para instalar uma versão mais antiga do pacote MarkDoc, digamos 3.8.0 . você pode digitar:
github install haghish/markdoc , version("3.8.0")
Mas onde você pode ver as versões dos pacotes? O GitHub possui uma guia de lançamento que lista todas as versões anteriores do software ( veja, por exemplo, as versões anteriores do MarkDoc ). Mas a boa notícia é que github tem um subcomando para listar todos os lançamentos anteriores nas janelas de resultados do Stata e permite que você instale qualquer um deles ( bem como as dependências de pacotes para aquela versão específica, se especificado ) com um único clique do mouse ou programaticamente. Para fazer isso, digite:
github query username/repository
Por exemplo, para listar as versões anteriores do MarkDoc , digite:
. github query haghish/markdoc
----------------------------------------
Version Release Date Install
----------------------------------------
3.8.5 2016-10-16 Install
3.8.4 2016-10-13 Install
3.8.3 2016-10-03 Install
3.8.2 2016-10-01 Install
3.8.1 2016-09-29 Install
3.8.0 2016-09-24 Install
3.7.9 2016-09-20 Install
3.7.8 2016-09-19 Install
3.7.7 2016-09-18 Install
3.7.6 2016-09-13 Install
3.7.5 2016-09-08 Install
3.7.4 2016-09-07 Install
3.7.3 2016-09-06 Install
3.7.2 2016-09-05 Install
3.7.0 2016-08-23 Install
3.6.9 2016-08-16 Install
3.6.7 2016-02-27 Install
----------------------------------------
Ao escrever uma análise com um software de documentação dinâmica, como o MarkDoc , você deve informar a versão dos pacotes que está usando em sua análise. Você pode obter a versão de um pacote instalado programaticamente usando o subcomando version , seguido por:
. github version markdoc
3.8.0
Este comando não tem outros usos porque o comando github list já mostra a versão dos pacotes instalados e também verifica se há uma versão mais recente deles disponível...
Alguns pacotes dependem de outros pacotes. O comando github permite instalar as dependências do pacote com ou sem uma versão específica. Para fazer isso:
dependency.do e inclua-o no repositóriogithub para instalar as dependências do pacote e até mesmo especificar a versão necessária.github procura dependency.do após instalar o pacote e se o encontrar no repositório, ele o executa. Por exemplo, o pacote MarkDoc possui um arquivo dependency.do que pode servir de exemplo de como o arquivo de dependência deve ser criado. Naturalmente, o arquivo dependenc.do só pode ser executado pelo comando github install .
O pacote github inclui um banco de dados de todos os arquivos instalados em pacotes hospedados no GitHub. Este é um recurso importante para os desenvolvedores evitarem a criação de um arquivo com um nome usado por outro desenvolvedor, pois tais pacotes não podem ser instalados juntos no mesmo sistema (o problema também existe para o nome do programa ). O pacote github permite que os desenvolvedores verifiquem se um nome específico já foi usado em um pacote antes.
O subcomando findfile pesquisa o githubfiles.dta (instalado com o pacote) e se encontrado, aponta o repositório que inclui o arquivo. Por exemplo, pesquisar arquivos que contenham a palavra-chave "dy" resultará em:
. github findfile dy
---------------------------------
Searching githubfiles database
---------------------------------
dynpandoc.ado
dynpandoc.sthlp
dynamicPage1.mata
---------------------------------
Esses arquivos também incluem o link para seus repositórios, se você clicar neles na janela de resultados.
Imagine que você criou um arquivo ado e arquivos de ajuda do Stata. Como você torna seu repositório instalável? Você precisa criar arquivos stata.toc e packagename.pkg manualmente, especificar as informações necessárias, arquivos que devem ser instalados, etc. O pacote github apresenta a GUI make que gera as instalações do pacote para você, usando um layout estrito. Você pode simplesmente selecionar os arquivos que deseja instalar, especificar as informações necessárias e ter seus arquivos toc e pkg prontos. Então, assim que você copiar esses arquivos para o seu repositório, ele estará instalável!
Mude o diretório de trabalho para o caminho do repositório e execute a GUI, digitando:
db make
anote as informações necessárias e selecione os arquivos que devem ser instalados. Pressione OK e divirta-se!
gitget O conjunto de dados gitget é baixado junto com o pacote github . Este conjunto de dados é atualizado mensalmente. Clique aqui para ver a lista completa de pacotes gitget .
EF Haghish
Centro de Biometria Médica e Informática Médica
Universidade de Friburgo, Alemanha
@Haghish
