Cite: Haghish, E. F. (2020). Developing, maintaining, and hosting Stata statistical software on GitHub. The Stata Journal, 20(4), 931-951.

GITHUB : a module for building, searching, installing, and managing Stata packages from GitHub

<a href="http://github.com/haghish/github"><img src="https://github.com/haghish/markdoc/raw/master/Resources/images/github3.png" align="left" width="140" hspace="10" vspace="6"></a>

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).

<br>

<img src="./images/news.png" width="140px" height="140px" align="left" hspace="10" vspace="6">NEWS: Introducing gitget command. gitget further simplifies installing and updating a package. it provides a database for all existing Stata packages on GitHub, which allows you to install a package that is hosted on GitHub - and is known by gitget, simply by typing:

gitget packagename

<img src="./images/white.png" width="140px" height="140px" align="left" hspace="10" vspace="6">The gitget command relies on a complete list of Stata packages on GitHub to identify the URL of a project. This list is created programmatically using a search program that detects Stata packages. First, all of the Stata repositories are identified and stored in repolist.dta. Next, the installable packages are extracted and stored in gitget.dta which also is installed with the package on your machine. The complete list of the archive is also available for preview within this repository

<br> <br>

Table of Contents

1. Introduction
2. Installation
3. Syntax
4. Subcommands
   1. Installing a package
   2. Searching for a Stata package
   3. Managing installed packages
   4. Checking a Stata repository
   5. Uninstalling a package
   6. Package Versions
      1. Installing a particular version
      2. Listing all previous releases
      3. Getting the version of an installed package
   7. Package dependencies
   8. Searching for a file in Stata packages
5. Building package installation files automatically
6. List of Stata Packages Recognized by gitget command

1. Introduction

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.

<center> <a href="https://github.com/haghish/github/raw/master/images/combined.png"><img src="https://github.com/haghish/github/raw/master/images/combined.png" width="650"></a> </center> <br>

2. Installing github module

You can install the latest version of the github command by executing the following code:

net install github, from("https://haghish.github.io/github/")

3. Syntax

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 | | findfile | searches for a filee among all Stata packages 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.

4. Subcommands

4.1 Installing a package

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 |

4.2 Searching for a Stata package

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

<center> <a href="https://github.com/haghish/github/raw/master/images/search.png"><img src="https://github.com/haghish/github/raw/master/images/search.png" width="400" hspace="10" vspace="6"></a> </center>

For example, if you use the github search command to search for markdoc package, you get the following output:

<center> <a href="https://github.com/haghish/github/raw/master/images/example.png"><img src="https://github.com/haghish/github/raw/master/images/example.png" width="650" hspace="10" vspace="6"></a> </center>

4.3 Managing installed packages

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

<center> <a href="https://github.com/haghish/github/raw/master/images/list.png"><img src="https://github.com/haghish/github/raw/master/images/list.png" width="650" hspace="10" vspace="6"></a> </center>

4.4 Checking a Stata repository

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

<img src="https://github.com/haghish/markdoc/raw/master/Resources/images/attention.png" width="20px" height="20px" align="left" hspace="0" vspace="0">This is rather important point to pay attention to because the github search command 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 option all in your search (in the search GUI check the **show GitHub repositories that are not in