version 1.3.3

Title

github -- search, install, and uninstall Stata packages with a particular
version (release) as well as their dependencies from
GitHub website

Syntax

github [ subcommand ] [ keyword | username/repository ] [, options]

The github command takes several subcommands:

subcommand

install installs the specified repository. The command should be
followed by the username/repository

uninstall uninstalls a package

query followed by username/repository, it makes a table of
all of the released versions of that package and allows you to install any version
with a single click.

check followed by a username/repository evaluates whether the
repository is installable (i.e. includes toc and pkg files

search followed by a keyword, it searches the GitHub API in
repository name (default), repository description, README.md file in
the repository, or all of the above. the in(str) option specifies the
field of the API search.

list GitHub API returns maximum of 100 research results. therefore,
a recursive search is needed to build the complete list of Stata packages on
GitHub. followed by a keyword (e.g. stata) the list command searches the
API within a specific time periods and aggregate the results to build the complete
list of Stata packages.

hot ranks the popular repositories on GitHub.

the language, all, and number options can be used to narrow
or expand the results.

Description

github simplifies searching and installing Stata packages from
GitHub website. The package also allows installing
older releaes of the package using the version() option, if the author
has made different release versions on GitHub. In addition, the command allows
the authors to specify package dependencies - that must be installed prior to
using the package - to be installed automatically.

If the dependencies are also hosted on GitHub, the author can specify a
particular version of the dependencies to ensure the software works with the
tested version of the dependencies. The information about the
package dependencies also appear in the github search command, allowing
the user to view the dependencies and their particular version that will be
installed automatically.

Options

The github command also takes several options for installing a package or
searching for a keyword. The table shows the options accordingly:

Installation Options
version(str) specifies a particular version (release tags) for
installing a new repository

force specifies that the downloaded files be installed even if the
packagename.pkg and Stata.toc files are missing. Use this option
wisely because by forcing the installation, you are installing a software that
is not prepared for installation.

Search Options
language(str) specifies the programming language of the repository.
the default is stata. To search for all programming languages related
to the keyword, specify language(all).

in(str) specifies the domain of the search which can be name (default)
description, readme, or all. To search for the keyword in
repository name, repository description, and the readme.md file,
specify in(all).

save(str) saves the results in a data set with the given name.

all shows repositories that lack the pkg and stata.toc
files. by default these repositories are not shown in the output because they
are not installable packages

append when the save option is specified, the append
option will add the new results to the saved dataset

replace when the save option is specified, the replace
option will replaces the dataset, if it exists

number(int) limits the number of displayed repositories.

created(str) filters the search results based on the date that the
repository was created on github. The date must be written with the format of
"yyyy-mm-dd" which is required by GitHub. This option can also specify
a range of time between two dates.
See the documentations on GitHub.

pushed(str) filters the search results based on the date that the
repository was last updated on github. The format for entering the date
is identical to the created option.

Installing package dependencies

Packages installed by github command can also automatically install the
package dependencies.
For example, the MarkDoc package
requires two other Stata packages which are
Weaver and
Statax.
Usually, users have to install these packages manually after installing
MarkDoc from GitHub or SSC. However, the github install command will look
for a file named dependency.do in the repository and executes this file
if it exists.

The dependency.do file will not be copied to the PLUS
directory and is simply executed by Stata after installing the package. It can
include a command for installing dependency packages using ssc,
net install, or github install commands. The latter is preferable because
it also allows you to specify a particular version for the dependency packages.

Note that the dependency.do file will only be executed by github install
command and other installation commands such as net install will not
install the dependencies.

Example(s)

examples of installing and uninstalling packages

install the latest version of MarkDoc package from GitHub
. github install haghish/markdoc

install MarkDoc version 3.8.1 from GitHub (older version)
. github haghish/markdoc, version("3.8.1")

Uninstall MarkDoc repository
. github uninstall markdoc

list all of the available versions of the MarkDoc package
. github query haghish/markdoc

examples of searching for a package

search for MarkDoc package on GitHub
. github search markdoc

search for a Stata package named "weaver"
. github search weaver, language(stata)

search for Stata packages that mention the keyword "likelihood"
. github search likelihood, language(stata) in(all)

search for a repository named "github" and published in November 2016
. github search github, created("2016-11-01..2016-11-30")

examples of searching the popular packages

view the top 10 packages (Stata installable) on GitHub
. github hot

view the top 50 packages (Stata installable) on GitHub
. github hot , number(50)

view the top 100 Stata repositories (including non-installable repos)
. github hot , number(100) all language(Stata)

build the complete list of Stata packages on GiutHub
. github list stata, language(all) in(all) all save(archive) append

Author

E. F. Haghish

Department of Mathematics and Computer Science (IMADA)

University of Southern Denmark

This help file was dynamically produced by
MarkDoc Literate Programming package