First Steps for Coauthors and RAs

  1. Ensure you have a GitHub account ID, and send it to me
  2. To get educational access (i.e. unlimited free repositories and other goodies) in GitHub
    • Student: Apply for the GitHub education pack, which will enable you to create private repositories, etc.
    • Professor: From your GitHub account, use Request a discount. It is easiest to do for your individual account, but you could also setup organizational account and submit requests here.
  3. Install the GitHub Client described below

Git Clients

To access Git repositories for shared projects, you will need a Git client. An easy one to use on OS/X and Windows is Github Desktop. A few pointers on the initial installation and setup of the first few repositories:

  1. After installation, the easiest way to clone a repository is to go to the link in GitHub, click "Clone or download", and then say "Open in Desktop".
  2. The first time you do this, it will ask you to run the executable on opening the link. Set this as the default behavior
  3. After that, you can choose the local directory you want the Clone to save in
Throughout GitHub, all comments, commit strings, and README files (and any file that ends in .md) uses Markdown for display.

General ETK Library Installation

You need to decide on a common location for the ETK library files and set environment variables accordingly.

Windows

  1. Consider choosing C:\working\libraries\ for consistency. Otherwise, keep paths as required.
  2. Open up a console with cmd and type: setx ETK_ROOT C:\working\libraries. Then close the cmd console
  3. If you didn't modify the folder, setting the environment variable is optional.

OS/X

  1. Consider making a top level folder such as ~/working/libraries/
  2. On OS/X, it is more painful to set environment variables which work with both a shell and Spotlight. See instructions,
    1. From a console, run sudo vi /etc/launchd.conf
    2. Edit the file to include a line: setenv ETK_PATH ~/working/libraries/
    3. Reboot the computer
  3. Alternatively, skip setting the environment variable ETK_ROOT and just use the folder suggestion above.

Specific ETK Libraries

See the following repositories, with instructions in the README.md
  1. Latex: See https://github.com/econtoolkit/latex.git. OS/X clone location is fragile.
  2. Matlab: Clone https://github.com/econtoolkit/matlab.git to /working/libraries/matlab
  3. Mathematica: Clone https://github.com/econtoolkit/mathematica.git to /working/libraries/mathematica
  4. Stata: Clone https://github.com/econtoolkit/stata.git to /working/libraries/stata

Basic Git Workflow

  1. "Pull" from the server before you start working on a particular project for the day. This avoids unnecessary conflicts if someone else changed the files, or you changed them on a different computer. In GitHub client, select the current repository and choose "Pull origin" at the top if there are any updates
  2. Plan and accomplish atomic tasks and "Commit" and then "Push" the files to the server as soon as you finish those small tasks. In GitHub Desktop, you will see the list of changed files on the left. Add in a summary of the change, and then "Commit to Master", then choose
  3. Put a comment in on the "Commit" which explains the change. This is for your future self as well as coauthors, and allows you to track all of the changes you made in case you need to see what changed (or rollback a version)
  4. If, while you are working, you want to rollback to the last version, right click on the file in GitHub Desktop, and either Discard all Changes, or choose which changes to discard
  5. If it absolutely impossible to break a change into smaller tasks that can individually finished in a day or so, then just be careful not to commit up files that "break the build" and make it unable to compile. If you absolutely must, then put a comment in that says something like: "Breaks build, in progress"

Git Basics (Emphasizing GitHub Desktop)

Some key concepts and background for those unfamiliar with Git (or those coming from SVN):

  • Git is a distributed VCS. This means that you have a local copy of the entire history, etc. of the version control for each project, but you can associate your copy with a remote server to push and pull changes.
  • It also means that there are separate steps in commiting to your local repository, and then pushing the local changes up to the remote repository
  • To initially get a copy of the repository from the server, you need to clone it. In GitHub desktop, this is easily done by choosing an option from the github webpage for the repository. Alternatively, you can choose "File/New repository..." in the menu and follow the instructions.
  • To put modified files up on the shared repository, you need to separately "Commit" the files to the local repository, and then "Push" the changes to the remote repository. To do this in GitHub Desktop, open the repository and see the list of all changes on the left. Put in a comment to "Commit to master". When you are ready to put them on the server, you will see "Push origin" at the top, which you can flick.
  • To see if there are any changes on the server (without making any local changes), the GitHub Desktop does a "Fetch" while it is open.. In the GitHub Desktop, it automatically does Fetch and shows the results at the top. If it says "Fetch orgin", it means no files have changed. If it says "Pull from origin" with a number, it means there are changes to bring down. Click that to get the latest.
  • A typical action is if you have local modifications, but want to go back to your last commited version. To do this, right click on any modified file in GitHub Desktop, and choose one of the "Discard" options.
  • When you click on files, the "Changes" tab shows show you the differences between the copy you have and the latest commit. Click on "History" to see the log of changes and see modified files
  • There are times when you may be modifying a local file when a change on the same file is pushed to the server. The GitHub Desktop may (or may not) notice this when it does a fetch from the server. Sometimes it may tell you to do a "Pull" first (which you can do in the menus). If you see a number going up, and another going down then both need to happen.
  • When the same file is modified by two people, Git is shockingly good at automatically merging both changes.
  • If it ever fails to merge, you will know because it will provide an error and say "We found some conflicts...". After this happens,
    1. Go to the offending file (if it is text) and you will see it has both sets of the conflicting text.
    2. Edit the file as required.
    3. Commit and push to the remote.
    4. If anything goes really wrong, then backup whatever files you have modified (not just the ones in conflict). Delete the repository and reclone it.