github
2.3.0
Citer : Haghish, EF (2020). Développer, maintenir et héberger le logiciel statistique Stata sur GitHub. Le Journal Stata, 20(4), 931-951.
github est un module Stata permettant de rechercher et d'installer des packages Stata à partir de GitHub, y compris les versions précédentes d'un package. Il s'agit d'une combinaison de plusieurs commandes Stata telles que search , findit et ssc , mais plutôt conçue pour gérer les packages Stata hébergés sur GitHub. De plus, le package fournit de nouvelles fonctionnalités de contrôle de version qui ne sont pas disponibles ailleurs pour les utilisateurs de Stata (par exemple, le package permet d'installer des versions plus anciennes d'un package Stata pour reproduire une analyse effectuée avec un logiciel plus ancien).
NEWS : Présentation de la commande gitget . gitget simplifie encore l'installation et la mise à jour d'un package. il fournit une base de données pour tous les packages Stata existants sur GitHub, ce qui vous permet d'installer un package hébergé sur GitHub - et connu par gitget , simplement en tapant :
gitget packagename
La commande gitget s'appuie sur une liste complète des packages Stata sur GitHub pour identifier l'URL d'un projet. Cette liste est créée par programme à l'aide d'un programme de recherche qui détecte les packages Stata. Tout d'abord, tous les référentiels Stata sont identifiés et stockés dans repolist.dta . Ensuite, les packages installables sont extraits et stockés dans gitget.dta qui est également installé avec le package sur votre machine. La liste complète de l'archive est également disponible en aperçu dans ce référentiel
Table des matières
gitget Ces dernières années, les utilisateurs de Stata utilisent de plus en plus GitHub pour partager du code et des ensembles de données Stata, développer des logiciels statistiques et héberger des packages Stata, comme le montre la figure ci-dessous. C’est en effet une bonne nouvelle pour la communauté Stata et pour tous ceux qui promeuvent la transparence de la recherche ! Le module github facilite la recherche, l'installation, la gestion et même la création de packages Stata. De plus, il permet d'installer une version de développement ou bien des versions stables d'un package. Il permet également de spécifier les dépendances des packages qui seront installées automatiquement, ce qui rend GitHub encore plus attrayant pour les utilisateurs et les développeurs de Stata. Ici, je vous montre rapidement comment installer et utiliser le package github .
github Vous pouvez installer la dernière version de la commande github en exécutant le code suivant :
net install github, from("https://haghish.github.io/github/")
La syntaxe générale du package peut être résumée comme suit :
github [subcommand] [...]
Où la [ sous-commande ] peut être :
| Sous-commande | Description |
|---|---|
search | trouve un package Stata sur GitHub |
findfile | recherche un fichier parmi tous les packages Stata sur GitHub |
install | installe un package depuis GitHub |
list | fournit des informations sur les packages installés avec github |
query | répertorie toutes les versions précédentes d'un package |
check | teste si un référentiel est installable |
uninstall | supprime un paquet de Stata |
update | met à jour un package depuis GitHub |
version | renvoie la version d'un package installé |
et le [ ... ] peut être le nom d'utilisateur/référentiel ou le nom du package en fonction de la sous-commande spécifiée.
Pour installer un package, tout ce dont vous avez besoin est le nom d'utilisateur GitHub et le nom du référentiel. La combinaison du nom d'utilisateur et du nom du référentiel - séparés par une barre oblique - fournit l'URL nécessaire au référentiel. Par exemple, pour installer le package MarkDoc, hébergé sur https://github.com/haghish/markdoc, il suffit de taper :
github install haghish/markdoc [, stable version("")]
Le package github comprend une base de données pour la liste complète des packages Stata hébergés sur GitHub. Par conséquent, vous pouvez également installer un package en spécifiant simplement le nom du package. La commande gitget - qui est un wrapper pour github install - peut installer ou mettre à jour les packages Stata depuis GitHub uniquement en demandant le nom du package :
gitget packagename [, stable version("")]
Par exemple, si vous souhaitez installer le package markdoc , taper gitget markdoc serait aussi simple que de taper github install haghish/markdoc . Si vous souhaitez inspecter la liste des packages Stata hébergés sur GitHub, consultez l'ensemble de données gitget.dta .
| Possibilités | Description |
|---|---|
stable | installe la dernière version stable du package |
version(str) | installe la version spécifiée |
Vous pouvez rechercher le package Stata sur GitHub à l’aide d’un ou de plusieurs mots-clés. Ceci est similaire aux commandes search ou findit de Stata, mais est uniquement utilisé pour rechercher des packages GitHub :
github search weaver
Rechercher efficacement l’API GitHub est très important. Pour cela, le package comprend une interface graphique de recherche qui affiche la syntaxe que vous pouvez utiliser pour affiner votre recherche ou l'étendre pour inclure d'autres sources. La commande de recherche analyse également les dates de sortie des packages hébergés sur la commande net , ce qui est une fonctionnalité très utile. Pour lancer l'interface graphique, tapez :
db github
Par exemple, si vous utilisez la commande github search pour rechercher le package markdoc , vous obtenez le résultat suivant :
github dispose d'une base de données intégrée qui assure le suivi des packages installés sur votre machine et, bien sûr, vous indique également les versions des packages installés sur la machine. La version est extraite des balises de version uniques du package, spécifiées par le développeur. Vous pouvez list les packages installés et obtenir des informations utiles à leur sujet. Cette commande vous avertit également si une mise à jour est disponible pour l'un de vos packages GitHub . Par exemple, dans le résultat ci-dessous, nous savons que des mises à jour sont disponibles pour deux de nos packages. nous pouvons également cliquer sur le lien (update) pour mettre à jour le package vers la dernière version.
. github list
Tous les packages ne sont pas installables. Les référentiels Stata doivent avoir des fichiers toc et pkg pour pouvoir être installés. Vous pouvez vérifier si un package est installable ou non à l'aide de la sous-commande check .
github check haghish/markdoc
C'est un point assez important auquel il faut prêter attention car la commande
github searchutilisée pour rechercher les packages Stata sur GitHub a tendance à ignorer les référentiels Stata qui ne sont pas installables. En d'autres termes, si votre référentiel n'inclut pas ces fichiers, il ne sera pas considéré comme un package Stata, sauf si vous spécifiez l'optionalldans votre recherche (dans l'interface graphique de recherche, cochez l'option afficher les référentiels GitHub qui ne sont pas installables ). Cependant, le packagegithubinclut également une interface graphique pour créer ces fichiers. En utilisant l'interface graphique fournie avecgithub, vous pouvez facilement créer ces fichiers pour votre référentiel (voir ci-dessous).
Pour installer un package, utilisez la sous-commande uninstall , suivie du nom du package. Par exemple:
github uninstall markdoc
GitHub permet d'archiver un nombre illimité de versions de packages. La commande github a une option pour spécifier la version du package, permettant d'installer les versions précédentes du package. Par exemple, pour installer une ancienne version du package MarkDoc, disons 3.8.0 . vous pouvez taper :
github install haghish/markdoc , version("3.8.0")
Mais où pouvez-vous voir les versions du package ? GitHub dispose d'un onglet de publication qui répertorie toutes les versions précédentes du logiciel ( voir par exemple les versions précédentes de MarkDoc ). Mais la bonne nouvelle est que github a une sous-commande pour répertorier toutes les versions précédentes dans les fenêtres de résultats Stata et vous permet d'installer n'importe laquelle d'entre elles ( ainsi que leurs dépendances de package pour cette version particulière, si spécifiée ) d'un simple clic de souris ou par programmation. Pour ce faire, tapez :
github query username/repository
Par exemple, pour répertorier les versions précédentes de MarkDoc , tapez :
. 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
----------------------------------------
Lorsque vous rédigez une analyse avec un logiciel de documentation dynamique, tel que MarkDoc , vous devez indiquer la version des packages utilisés dans votre analyse. Vous pouvez obtenir la version d'un package installé par programme en utilisant la sous-commande version , suivie du :
. github version markdoc
3.8.0
Cette commande n'a aucune autre utilisation car la commande github list affiche déjà la version des packages installés et vérifie également si une version plus récente de ceux-ci est disponible...
Certains packages s'appuient sur d'autres packages. La commande github permet d'installer les dépendances du package avec ou sans version spécifique. Pour ce faire :
dependency.do et incluez-le dans le référentielgithub pour installer les dépendances du package et spécifiez même la version requise.github recherche dependency.do après l'installation du package et si elle le trouve dans le référentiel, elle l'exécute. Par exemple, le package MarkDoc contient un fichier dependency.do qui peut servir d'exemple sur la façon dont le fichier de dépendances doit être créé. Naturellement, le fichier dependenc.do n'est exécutable que par la commande github install .
Le package github comprend une base de données de tous les fichiers installés dans les packages hébergés sur GitHub. Il s'agit d'une fonctionnalité importante pour que les développeurs évitent de créer un fichier avec un nom utilisé par un autre développeur car de tels packages ne peuvent pas être installés ensemble sur le même système (le problème existe également pour le nom du programme ). Le package github permet aux développeurs de vérifier si un nom particulier a déjà été utilisé dans un package.
La sous-commande findfile recherche le githubfiles.dta (installé avec le package) et si elle est trouvée, elle indique le référentiel qui inclut le fichier. Par exemple, la recherche de fichiers contenant le mot-clé « dy » entraînera :
. github findfile dy
---------------------------------
Searching githubfiles database
---------------------------------
dynpandoc.ado
dynpandoc.sthlp
dynamicPage1.mata
---------------------------------
Ces fichiers incluent également le lien vers leurs référentiels, si vous cliquez dessus dans la fenêtre des résultats.
Imaginez que vous avez créé un fichier ado et des fichiers d'aide Stata. Comment rendre votre référentiel installable ? Vous devez créer manuellement un fichier stata.toc et un packagename.pkg , spécifier les informations requises, les fichiers à installer, etc. Le package github introduit l'interface graphique make qui génère les installations de package pour vous, en utilisant une présentation stricte. Vous pouvez simplement sélectionner les fichiers que vous souhaitez installer, spécifier les informations requises et préparer vos fichiers toc et pkg . Ensuite, dès que vous copiez ces fichiers dans votre référentiel, il sera installable !
Remplacez le répertoire de travail par le chemin du référentiel, puis exécutez l'interface graphique en tapant :
db make
notez les informations requises et sélectionnez les fichiers à installer. Appuyez sur OK et profitez-en !
gitget L'ensemble de données gitget est téléchargé avec le package github . Cet ensemble de données est mis à jour mensuellement. Cliquez ici pour voir la liste complète des packages gitget .
EF Haghish
Centre de biométrie médicale et d'informatique médicale
Université de Fribourg, Allemagne
@Haghish
