github is a Stata module for searching and installing Stata packages from GitHub, including previous releases of
a package. It is a combination of several Stata commands such as search, findit, and ssc, but instead, made for managing Stata packages hosted on GitHub. In addition, the package provides new features for version control which are not available to Stata users elsewhere (for example, the package allows installing older releases of a Stata package to reproduce an analysis carried out with older software).
You can install the latest version of the github command by executing the following code:
net install github, from("https://haghish.github.io/github/")
To install a package, all you need is the GitHub username and the name of the repository. For example, to install MarkDoc package, it is enough to type:
github install haghish/markdoc
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. The search subcommand automatically checks for this.
github check haghish/markdoc
to make your repository installable, you need packagename.pkg and stata.toc files. The MarkDoc Package can automatically build these files for you, making your package ready to be installable from any platform.
githubpackage provide an option namedforcethat allows you to force install repositories which are not installable. However, the package still gives more credit to installable packages when using thegithub searchcommand. Therefore, by making your package installable, you will receive much more attention from Stata users on GitHub. Using MarkDoc Package you can write the Stata help files using Markdown and build the toc and pkg files effortlessly.
To install a package, use the uninstall subcommand, followed by the package name. For example:
github uninstall markdoc
You can search GitHub for Stata package using a keyword. Read the help file for more information. This is similar to Stata's search or findit commands, but instead, only used for searching GitHub packages:
github search weaver, in(all)
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
----------------------------------------
Some package rely on other packages. The github command allows you to install the package
dependencies with the specified 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 (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 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.
The repository should include a file with .pkg suffix and an identical name as the package name.
The name of the file doesn't have to be identical to the repository name, but it is strongly adviced
to name the repository identical to the package name. Below is an example file
of the github.pkg that is used for installing the package on your system.
Note that the files that are meant to be copied on your system begin with F (bottom of the file)
d 'GITHUB': module to install Stata packages and their dependencies from GitHub
d
d github is a module for installing Stata packages with a particular
d version as well as their dependencies from GitHub.
d
d KW: Version control
d KW: GitHub
d KW: Git
d KW: net
d
d Requires: Stata version 11
d
d Distribution-Date: 20161103
d
d Author: E.F. Haghish, University of Southern Denmark
d Support: email haghish@imada.sdu.dk
d
F github.ado
F github.sthlp
F githubQuery.ado
E. F. Haghish
Center for Medical Biometry and Medical Informatics
University of Freiburg, Germany
@Haghish