.md .pdf

Contents

GitHub

Aims / Outcomes / Expectations:

1. Provide an overview of GitHub and git

2. Demo: GitHub and features recommended for this workshop

3. Provide resources for interested participants

What is GitHub?

The competitors are mainly:

1. Gitlab

2. Atlassian BitBucket

It is a website that hosts Git projects and adds an interface for:

1. tracking issues,

2. reduce complexity of code reviews, and

3. simplifies collaboration on projects

4. enables web integrations (i.e. automated workflows)

GitHub is ideally suited to software projects, but it is general enough to be used for any projects (with a particular emphasis on text based files).

GitHub consists of users (individuals) and organisations for grouping projects in an organisation setting such as QuantEcon

Here are the 2020 year in review statistics

There is a useful training guide that is put together by the GitHub team.

Another access option is to use Github Desktop but I find the website to be my preferred access option coupled with terminal based workflows with git.

Tip

If you are solely interested in LaTeX projects there are other services available that offer collaboration features such as overleaf but requires a paid account.

What is Git?

Git is a distributed version control system that sits on top of your file system that tracks the state of a collection of files.

Its major strength is text type data (manuscripts, code etc.) but can keep track of other file types also.

It can help you determine exactly what has changed, why it has changed, and who has changed it.

Key Concepts of Git

1. Working Directory

2. Staging Area

3. Local Repository (Repo)

4. Remote Repository (Repo)

as git is distributed the local and remote repositories have access to the same history information.

Git Workflow

Image courtesy of this tutorial

A file in a Working Directory can have one of the following three states

1. Modified changes detected

2. Staged changes are marked to be committed

3. Commited changes stored in local repository

Note

You can find the status of files using:

git status

Setting up Git

When using Git for the first time it can be a good idea to setup Git with the correct user information.

Open a terminal (or Git Bash (Windows)):

$ git config --global user.name "Your name here"
$ git config --global user.email "your_email@example.com"

Note

You can check the configuration using:

git config --list

Setting up a Repository (GitHub)

Go to GitHub (in browser) and click on New

New Repository

To setup a new repository

Tip

Click on Clone and copy the url such as: https://github.com/<username>/test.git to your clipboard to use when cloning.

Cloning your Repository

To get a copy of the repository on your local machine

Open a terminal:

cd <working-directory>
git clone https://github.com/<username>/<repo-name>.git

Fetching the latest from GitHub

If you already have a local copy of the repository on your local computer then you should always fetch the latest changes before starting your work.

Open a terminal:

git pull

this is particularly the case in collaborative environments.

Adding a Change

Navigate to the repository via terminal

Create a file such as first.txt and use:

git status

to check on git state

Committing a Change (Local)

We will want to move the file first.txt into the staging area in preparation for committing.

In Terminal:

git add first.txt

Once we have added the files we want to commit them to history

In Terminal:

git commit -m "initial commit"

Pushing a Change (GitHub)

To get those changes on your remote GitHub copy of the repository we need to push them to GitHub:

In Terminal:

Note

On collaborative projects you rarely push to master

git push origin master

Viewing results on GitHub

(Optional) Git - Advanced

Git has a lot of features:

1. Forking

2. Branching

3. Rebasing

4. Tagging

5. Stashing

6. …

we will run through branching

Branching

A branch is like a parallel copy of the master/main branch.

It allows changes to occur in parallel.

The master/main branch does not get modified until the branch is merged into the main** branch.

Using GitHub this is called a pull request.

Setting up a Branch:

Let’s setup a branch

git checkout -b first-branch

and then add a file second.txt and/or modify first.txt

Adding a Change:

We now want to follow the same commit workflow as before

git add second.txt
git commit -m "adding a second file"

Pushing the Change:

Pushing this branch to GitHub’s copy of the test repo

Note

The origin is automatically configured to GitHub when you cloned the repository from GitHub

git push origin first-branch

Setup a PR on GitHub:

Look for:

then setup a PR by clicking on Compare and pull request

Suggested Workflows

Key GIT Commands

The vast majority of interactions with git is focused on these commands

1. git status

2. git pull

3. git checkout -b <branch-name>

4. git add

5. git commit -m "message"

6. git push

A Common Terminal Workflow

1. git pull : retrieve new updates

2. git status : show status of commit

3. General work and edits

4. git status : show status of commit

5. git add . : puts all changed files into staging area

6. git commit -m "some message" : commit changes to local git repository with a description

7. git push : pushes the new version to Github

Further Reading / Resources

Git Resources

Understanding Git:

1. Github Tutorials

2. Git Book

3. Blog: Beginners

4. Blog: Git Guide

5. Blog: Git Quickstart

6. Blog: Useful Git Commands

GUI Options (OS X and Windows):

Some like to start by using a GUI

1. Git Fork

2. Git Kraken

I typically recommend terminal based workflows

Exercise

Exercise 1 (Exercise 1: Clone Workshop Repository)

Clone the workshop repository:

git clone https://github.com/QuantEcon/2021-workshop-rsit.git

(Demo) Replicating the ProductSpace Session 2 (Python Fundamentals)