github.sthlp

{smcl}
{it:v. 2.3.0}


{title:github}

{p 4 4 2}
{bf:github} is a program for searching, installing, and managing Stata packages 
{space 1}as well as their dependencies from 
{browse "http://www.github.com/haghish/github":GitHub} website


{title:Syntax}

{p 8 8 2} {bf:github} [ {it:subcommand} ] [ {it:keyword} | {it:username/repository} ] [, {it:options} ]


{p 4 4 2}
where the subcommands can be:

{col 5}{it:subcommand}{col 19}{it:Description}
{space 4}{hline}
{col 5}install{col 19}followed by the {it:username/repository}, installs the specified repository
{col 5}require{col 19}followed by {it:username/repository}, examines the required version (see below)
{col 5}query{col 19}followed by {it:username/repository}, returns all released versions of that package
{col 5}check{col 19}followed by {it:username/repository}, evaluates whether the repository is installable
{col 5}uninstall{col 19}followed by {it:package name}, uninstalls a package
{col 5}search{col 19}followed by {it:keywords}, it searches the GitHub API for relevant packages or repositories
{col 5}findfile{col 19}followed by a {it:keyword}, it searches Stata packages for files that include the keyword
{col 5}list{col 19}lists the packages installed from GitHub and checkes if they have an update
{col 5}version{col 19}return the version of installed package or set a minimum required version
{space 4}{hline}

{title:Description}

{p 4 4 2}
{bf:github} simplifies searching and installing Stata packages from 
{browse "http://www.github.com/":GitHub} website. The package also allows installing 
older releaes of the package using the {bf: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. 

{p 4 4 2}
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 {bf:github search} command, allowing 
the user to view the dependencies and their particular version that will be 
installed automatically. 


{title:Options}

{p 4 4 2}
The {bf:github} command also takes several options for installing a package or 
searching for a keyword. The table shows the options accordingly:


{p 4 4 2}{bf:{bf:github install} options:}

{col 5}{it:option}{col 18}{it:Description}
{space 4}{hline}
{col 5}package({it:str}){col 18}the package name. only needed if the repository name is not identical to the package name
{col 5}stable{col 18}installs the latest stable release. otherwise the main branch is installed
{col 5}verson({it:str}){col 18}specifies a particular stable version (release tags) for the installation
{space 4}{hline}

{p 4 4 2}{bf:{bf:github search} options:}

{col 5}{it:option}{col 20}{it:Description}
{space 4}{hline}
{col 5}language({it:str}){col 20}specifies the programming language of the repository. the default is {bf:Stata}
{col 5}in({it:str}){col 20}specifies the domain of the search which can be {bf:name}, {bf:description}, {bf:readme}, or {bf:all}
{col 5}all{col 20}shows repositories that lack the {bf:pkg} and {bf:stata.toc} files in the search results
{col 5}save(filename){col 20}stores the search results in a dataset
{col 5}replace{col 20}replaces the existing dataset
{space 4}{hline}

{title:Installing package dependencies}

{p 4 4 2}
Packages installed by {bf:github} command can also automatically install the 
package dependencies. The {bf:github install} command will look 
for a file named {bf:dependency.do} in the repository and executes this file 
if it exists. 

{p 4 4 2}
The {bf: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 {bf:ssc}, 
{bf:net install}, or {bf:github install} commands. The latter is preferable because 
it also allows you to specify a particular version for the dependency packages. 

{p 4 4 2}
Note that the {bf:dependency.do} file will only be executed by {bf:github install} 
command and other installation commands such as {bf:net install} will not 
install the dependencies. 


{title:Examples}

{p 4 4 2}{bf:examples of installing and uninstalling packages}

{p 4 4 2}
install the latest development version of MarkDoc package 

        . github install haghish/markdoc

{p 4 4 2}
install the latest stable version of MarkDoc package

        . github install haghish/markdoc, stable

{p 4 4 2}
install MarkDoc version 3.8.1 from GitHub (older version)

        . github install haghish/markdoc, version("3.8.1")

{p 4 4 2}
Uninstall MarkDoc repository

        . github uninstall markdoc

{p 4 4 2}
list all of the available versions of the MarkDoc package

        . github query haghish/markdoc

{p 4 4 2}{bf:examples of searching for a package}

{p 4 4 2}
search for MarkDoc package on GitHub

        . github search markdoc

{p 4 4 2}
search for a Stata package named "weaver"

        . github search weaver, language(stata)

{p 4 4 2}
search for Stata packages that mention the keyword "likelihood" 

        . github search likelihood, language(stata) in(all)

{p 4 4 2}
search for a script files with the name {it:dy}

        . github findfile dy

{p 4 4 2}{bf:example of package management}

{p 4 4 2}
list the installed packages

        . github list

{p 4 4 2}
get the version of an installed packages, e.g. markdoc package

        . github version markdoc

{p 4 4 2}{bf:examples of searching the popular packages}

{p 4 4 2}
search for Stata packages on GiutHub and save the search results in a data set

    . github search stata, language(Stata) save(archive) 


{title:Author}

{p 4 4 2}
E. F. Haghish     {break}
Department of Mathematics and Computer Science (IMADA)      {break}
University of Southern Denmark      {break}

{space 4}{hline}

{p 4 4 2}
This help file was dynamically produced by 
{browse "http://www.haghish.com/markdoc/":MarkDoc Literate Programming package}