github.sthlp

{smcl}
{right:version 1.9.1}
{title:Title}

{phang}
{cmd:github} {hline 2} search, install, and uninstall Stata packages with a particular    {break} version (release) as well as their dependencies from 
 {browse "http://www.github.com/haghish/github":GitHub} website
 

{title:Syntax}

{p 8 16 2}
{cmd: github} [ {help github##subcommand:{it:subcommand}} ] [ {it:keywords} | {it:username/repository} ] [{cmd:,} options]
{p_end}

{p 4 4 2}
The {bf:github} command takes several subcommands:

{marker subcommand}{...}
{synoptset 20 tabbed}{...}
{synopthdr:subcommand}
{synoptline}
{synopt:{opt search}}followed by {it:keywords}, it searches the GitHub API and Stata.com for Stata packages and repositories.{p_end}
{synopt:{opt install}}installs the specified repository. The command should be 
followed by the {bf:username/repository}{p_end}
{synopt:{opt query}}followed by {bf: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.{p_end}
{synopt:{opt check}}followed by a {bf:username/repository} evaluates whether the 
repository is installable (i.e. includes {bf:toc} and {bf:pkg} files{p_end}
{synopt:{opt uninstall}}uninstalls a package. the command should be followed by a {it:package-name}.{p_end}
{synopt:{opt update}}updates a package. the command should be followed by a {it:package-name}.{p_end}
{synopt:{opt list}}lists the installed packages from GitHub and allows updating or uninstalling them. {p_end}
{synoptline}
{p2colreset}{...}


{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:

{* the new Stata help format of putting detail before generality}{...}
{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Installation Options}
{synopt:{opt stable}}will install the latest released version of the software. otherwise, the depelopment version of the package will be installed.{p_end}
{synopt:{opt v:ersion(str)}}specifies a particular stable version (release tags) for 
installing a new repository{p_end}
{synopt:{opt 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. {p_end}

{syntab:Search Options}
{synopt:{opt language(str)}}specifies the programming language of the repository. 
the default is {bf:stata}. To search for all programming languages related 
to the {it:keyword}, specify {bf:language(all)}. {p_end}
{synopt:{opt in(str)}}specifies the domain of the search which can be {bf:name} (default) 
{bf:description}, {bf:readme}, or {bf:all}. To search for the {it:keyword} in 
repository name, repository description, and the readme.md file, 
specify {bf:in(all)}. {p_end}
{synopt:{opt all}}shows repositories that lack the {bf:pkg} and {bf:stata.toc} 
files. by default these repositories are not shown in the output because they 
are not installable packages {p_end}
{synopt:{opt net}}it includes results from Stata.com website, analyzes them, and shows the 
publication date of the packages{p_end}
{synopt:{opt local}}it includes results from Stata.com website that might include 
documents other than packages, such as help files, FAQs, Stata Journal articles, etc.{p_end}
{synoptline}
{p2colreset}{...}



{title:Installing package dependencies}

{p 4 4 2}
Packages installed by {bf:github} command can also automatically install the 
package dependencies. 
For example, the {browse "https://github.com/haghish/MarkDoc":MarkDoc} package 
requires two other Stata packages which are 
{browse "https://github.com/haghish/weaver":Weaver} and
{browse "https://github.com/haghish/MarkDoc":Statax}. 
Usually, users have to install these packages manually after installing 
MarkDoc from GitHub or SSC. However, 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:Example(s)}

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

    {it:install the latest developing version of MarkDoc package from GitHub}
        . github install haghish/markdoc
      {it:or}
        . gitget markdoc
		
    {it:install the latest released stable version of MarkDoc package from GitHub}
        . github install haghish/markdoc , stable
      {it:or}
        . gitget markdoc, stable

    {it:install MarkDoc version 3.8.1 from GitHub (older version)}
        . github haghish/markdoc, version("3.8.1")
      {it:or}
        . gitget markdoc, version("3.8.1")
		
    {it:Uninstall MarkDoc repository}
        . github uninstall markdoc
		
    {it: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} 
		
    {it:search for MarkDoc package on GitHub}
        . github search markdoc
		
    {it:search for a Stata package named "weaver"}
        . github search weaver, language(stata)
	
    {it:search for Stata packages that mention the keyword "likelihood" }
        . github search likelihood, language(stata) in(all)


{p 4 4 2}
{bf:listing and managing the installed packages from GiutHub} 
		
        . github list
		

{title:Author}

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

    {hline}

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