4 Stata and Github

In this chapter you will learn how to install Stata commands from Github and how to make sure your Stata session reads packages that you have cloned from a github repository. In this chapter, we refer to any general command a ccc but that means any Stata command name.

4.1 Stata ado-path

The first thing to understand is how Stata read Stata commands commonly saved in .ado file. When you execute a command, Stata begins to search for your command in a set of directories stored in the global macro ${S_ADO}, which is known in Stata documentation as the ado-path. An easy way to see your ado-path is to type, adopath in Stata.

adopath
. adopath
  [1]  (BASE)      "C:\Program Files\Stata16\ado\base/"
  [2]  (SITE)      "C:\Program Files\Stata16\ado\site/"
  [3]              "."
  [4]  (PERSONAL)  "c:\ado\personal/"
  [5]  (PLUS)      "c:\ado\plus/"
  [6]  (OLDPLACE)  "c:\ado/"

The folder in which you placed your ado-file is important because Stata searches throughout the folders in the order in which they are listed in the ado-path. So, if you have two ado-files with the same name, one in c:\ado\personal and the other one in c:\ado\plus, Stata will compile the one in c:\ado\personal because it is listed first. To make sure where Stata is reading from your ado-file, you can type which ccc, where ccc stands for the name of your command

The directories above are the basic set with which Stata comes from factory. These directories are standard in Stata and you can’t modify them. However, you can add more directories to the ado-path so that Stata searched for your ado-files in there too. One thing to keep in mind is that the sysdir in Stata provides similar information than adopath, but it is not the same. The sysdir command only lists the basic directories in which Stata searches for commands, but not the ones you have added manually. Also, for some reason, it does not list the directories in the order in which Stata search inside of them. Notice that when you type sysdir the directories are not numbered, in contrast to adopath.

. sysdir
   STATA:  C:\Program Files\Stata16\
    BASE:  C:\Program Files\Stata16\ado\base\
    SITE:  C:\Program Files\Stata16\ado\site\
    PLUS:  c:\ado\plus\
PERSONAL:  c:\ado\personal\
OLDPLACE:  c:\ado\

4.2 Installing commands from Github

You have probably install commands in Stata using the directive ssc install ccc. Each time you do that, Stata will save the command in the c:\ado\plus\?\ folder, where ? stands for the first letter of the name of the command you installed. Now, when you install a command from github, Stata will save it in c:\ado\plus\?\ as well.

In order for a command to be installed properly, Stata needs to find, besides your ado-file/s and any other installation file, two additional files, stata.toc and ccc.pkg. We won’t go into the details of these files, but the important thing to keep in mind is that as long as those files are in the folder in which your ado-file is, Stata can install it via the command net. We provide you with three different methods to install commands from github.

4.2.1 Recommended method

E. F.Haghish created a very nice Stata wrapper of the net command to install commands from github. Not surprisingly, the name of the command is github. And, as you have probably guessed it, you will install it using the net if you don’t have github installed already.

In order to install the github command, you can type

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

Now, you can install any command in Github typing github install username/ccc , where username refers to the Github username and ccc to the name of the Github repository, which, ideally, should be the same as the name of your command.

We recommend this method because the github command has many other features that allow you to manipulate and manage your Stata commands downloaded from Github. You can see some of the features in the github command page.

4.2.2 Alternative method

Alternatively you could install the package by typing the following line,

net install ccc, from("https://raw.githubusercontent.com/username/ccc/master/")

This method is reliable but you don’t get the nice features of the github command. Please note that the path is a little different from the one you used to install the github command. Just notice the where username/ccc part is in the link.

4.2.3 Last resource method

use only this method just in case the methods above do not work due to firewall restrictions

Click on the green icon “Clone or Download” above.
Download the package as a zip. It does not really matter where you save this zip file.
Extract the files with extension .ado and .sthlp only, and place them in the directory c:/ado/plus/p. You need to place them in this folder only. Otherwise, it won’t work.
type discard in Stata.

4.3 Cloning the Stata command repository

When you install a command from Github of from SSC, you expect the command to work properly and you will find no issues with it. Unfortunately, that is not always the case. So, you will need to make the modifications by yourself. When this happens you should never modify the version in c:/ado/plus/p. That folder is just for installed ado-files, not for editing ado-files. When Stata is updated, you will loose all your changes. Also, it not a good practice.

The solution to this problem is to clone the repository in a different folder, modify it in there and then push it back, creating a pull request.

In order to set up Stata correctly to read ado-files in the cloned folder, make sure to follow the instructions in this blog.

3 Collaboration in Git

5 Introduction to PovcalNet Update