Table of Contents
- Introduction
- Installation
- Syntax
- Subcommands
- Building package installation files automatically
- List of Stata Packages Recognized by
gitgetcommand
In the recent years, Stata users have been increasingly using GitHub for sharing Stata code and datasets, developing statistical software, and hosting Stata packages, as shown in the figure below. This is indeed a good news for the Stata community and anyone promoting research transparency! The github module, facilitates searching, installing, managing, and even building Stata packages. Furthermore, it allows installing development version or alternatively, stable releases of a package. It also allows specifying package dependencies that will be installed automatically, making GitHub even more appealing for Stata users and developers. Here, I quickly show you how to install and use the github package.
You can install the latest version of the github command by executing the following code:
net install github, from("https://haghish.github.io/github/")
The general syntax of the package can be summarized as:
github [subcommand] [...]
Where the [subcommand] can be:
| Subcommand | Description |
|---|---|
search |
finds a Stata package on GitHub |
install |
installs a package from GitHub |
list |
provides information about packages installed with github |
query |
lists all previous releases of a packag |
check |
tests whether a repository is installable |
uninstall |
removes a package from Stata |
update |
updates a package from GitHub |
version |
returns the version of an installed package |
and the [...] can be whether username/repository or packagename based on the specified subcommand.
To install a package, all you need is the GitHub username and the name of the repository. The combination of username and repository name - seperated by a slash - provides the needed URL to the repository. For example, to install MarkDoc package, which is hosted on https://github.com/haghish/markdoc, it is enough to type:
github install haghish/markdoc [, stable version("")]
The github package includes a database for the complete list of Stata packages hosted on GitHub. Therefore, you can also install a package just by specifying the package name. The gitget command - which is a wrapper for github install - can install or update Stata packages from GitHub only by asking the package name:
gitget packagename [, stable version("")]
For example, if you wish to install markdoc package, typing gitget markdoc would be as goo as typing github install haghish/markdoc. If you wish to inspect the list of Stata packages hosted on GitHub, see the gitget.dta data set.
| Options | Description |
|---|---|
stable |
installs the latest stable release version of the package |
version(str) |
installs the specified release version |
You can search GitHub for Stata package using a keyword or many keywords. This is similar to Stata's search or findit commands, but instead, only used for searching GitHub packages:
github search weaver
Searching GitHub API effectively is very important. For this, the package includes a search GUI that shows the syntax you can use to narrow down your search or expand it to include other sources. The search command also analyzes the release dates for packages hosted on the net command, which is a very useful feature. To launch the GUI, type:
db github
For example, if you use the github search command to search for markdoc package, you get the following output:
github has a built-in database that keeps track of the packages installed on your machine, and of course, also tells you the versions of the packages installed on the machine. The version is taken from the unique release tags of the package, specified by the developer. You can list the installed packages and get helpful information about them. This command also notifies you if there is an available update for any of your GitHub packages. For example, in the output below, we know that there are updates available for two of our packages. we can also click on the (update) link to update the package to the latest release.
. github list
Not all packages are installable. Stata repositories must have toc and pkg files in order to be installable. You can check whether a package is installable or not using the check subcommand.
github check haghish/markdoc
This is rather important point to pay attention to because the
github searchcommand that is used for searching Stata packages on GitHub, tends to dismiss Stata repositories that are not installable. In other words, if your repository does not include these files, it will not be considered a Stata package, unless you specify the optionallin your search (in the search GUI check the show GitHub repositories that are not installable option). However, thegithubpackage also includes a GUI for building these files. Using the GUI that comes withgithub, you can easily build these files for your repository (see below).
To install a package, use the uninstall subcommand, followed by the package name. For example:
github uninstall markdoc
GitHub allows archiving unlimited number of package versions. The github command has an option for specifying
the package version, allowing installing previous package versions. For example, for installing an older
version of MarkDoc package, say 3.8.0. you can type:
github install haghish/markdoc , version("3.8.0")
But were can you see the package versions? GitHub has a release tab that lists all of the previous releases of the software (See for example the previous releases of MarkDoc). But the good news is that github has a subcommand for listing all of the previous releases in Stata results windows and allows you to install any of them (as well as their package dependencies for that particular version, if specified) with a single mouse click or programmatically. To do so, type:
github query username/repository
For example, to list MarkDoc's previous releases, type:
. 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
----------------------------------------
When writing an analysis with a dynamic documentation software, such as MarkDoc, you should report the version of the packages that use are using in your analysis. You can obtain the version of an installed package programmatically using the version subcommand, followed by the :
. github version markdoc
3.8.0
This command does not have any other uses because the github list command already shows the version of the installed packages and also checks whether there is a newer version of them available...
Some packages rely on other packages. The github command allows you to install the package
dependencies with or without a specific version. To do so:
- create a file named
dependency.doand include it in the repository - this file is not meant to be installed in the PLUS directory therefore it should not be mentioned in the pkg file, when you are building the package (see below)
- include the code for installing the package dependencies in this do file. If the packages
are hosted on GitHub, use the
githubcommand for installing the package dependencies and even specify the requiered version. githubcommand looks fordependency.doafter installing the package and if it finds it in the repository, it executes it.
For example, MarkDoc package has a dependency.do file that can serve as an example how the dependency file should be created. Naturally, the dependenc.do file is only executable by github install command.
Imagine you have created an ado-file and Stata help files. How do you make your repository installable? You need to create a stata.toc aand a packagename.pkg files manually, specify the required information, files that should be installed, etc. The github package introduces the make GUI that generates the package installations for you, using a strict layout. You can just select the files that you wish to install, specify the required information, and have your toc and pkg files ready. Then, as soon as you copy these files to your repository, it would be installable!
Change the working directory to the repository path and then run the GUI, typing:
db make
write down the required information and select the files that should be installed. Press OK, and enjoy!
The gitget data set is downloaded along with github package. This data set is updated monthly. Click here to see the complete list of gitget packages.
E. F. Haghish
Center for Medical Biometry and Medical Informatics
University of Freiburg, Germany
@Haghish