9  Git & GitHub

9.1 What is Git and Why Use Version Control?

Git is a version control system - software that tracks changes to your files over time. Think of it as an extremely powerful "undo" button that remembers every version of every file you have ever saved.

The Problem Git Solves

As researchers, we have all been here:

This approach has serious problems:

• No clear history: Which version fixed that bug? When did we change the regression specification?
• Collaboration chaos: When two people edit the same file, someone's work gets overwritten
• Disk clutter: Dozens of nearly-identical files taking up space
• Reproducibility nightmare: Which exact code produced the results in the paper?

What Git Does for You

Git vs. GitHub: What is the Difference?

This confuses many beginners, so let us be clear:

Why Economists and Researchers Need Git

Version control is not just for software developers. Here is why it matters for empirical research:

1. Journal requirements: Many journals now require replication packages with version-controlled code
2. Collaboration: Work with coauthors without emailing files back and forth
3. Pre-registration: Commit your analysis plan before seeing results to demonstrate credibility
4. Error tracking: When a referee finds a bug, trace exactly when it was introduced
5. Career: GitHub profiles increasingly serve as portfolios for academic and industry jobs

9.2 Key Git Concepts

Before diving into commands, let us understand the core concepts. These terms will appear constantly, so it is worth taking time to understand them properly.

Repository (Repo)

A repository is a project folder that Git is tracking. It contains all your project files plus a hidden .git folder where Git stores the complete history.

There are two types of repositories:

• Local repository: Lives on your computer. This is where you do your work.
• Remote repository: Lives on a server (like GitHub). This is for backup and collaboration.

Commit

A commit is a saved snapshot of your project at a specific moment. Each commit records:

• What files changed
• What the changes were (line by line)
• Who made the changes
• When the changes were made
• A message describing why the changes were made

Each commit has a unique identifier (called a hash or SHA) - a long string like a1b2c3d4e5f6.... Usually you only need the first 7 characters to identify a commit uniquely.

Branch

A branch is an independent line of development. The default branch is typically called main (or master in older projects).

Common branch usage:

• main - The stable, production-ready version
• feature-new-regression - Adding a new analysis
• fix-data-cleaning - Fixing a bug in data processing
• experiment-ml-approach - Trying a machine learning method

Remote

A remote is a connection to a repository stored somewhere else (usually on GitHub). The default remote is conventionally named origin.

When you push, you send your local commits to the remote. When you pull, you download commits from the remote to your local repository.

The Three States of Files

In Git, files exist in one of three states, which correspond to three areas:

Quick Reference: Git Vocabulary

9.3 The Git Workflow Explained Simply

The basic Git workflow has just four steps that you will repeat over and over. Once you understand this pattern, Git becomes much less intimidating.

The Basic Workflow

git add analysis.py          # Stage one file
git add .                    # Stage all changed files

git commit -m "Add regression with robust standard errors"

git push origin main

A Day in the Life

Here is what a typical Git workflow looks like during a research project:

# Morning: Start work, get latest changes from collaborators
$ git pull origin main

# ... you work on the analysis for a few hours ...

# Check what you have changed
$ git status

# See the specific changes line-by-line
$ git diff

# Stage your changes
$ git add analysis.py utils.py

# Commit with a meaningful message
$ git commit -m "Fix data cleaning bug and add summary statistics"

# End of day: Push to GitHub for backup
$ git push origin main

$ git pull origin main
Already up to date.

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add ..." to update what will be committed)
        modified:   analysis.py
        modified:   utils.py

$ git diff
diff --git a/analysis.py b/analysis.py
--- a/analysis.py
+++ b/analysis.py
@@ -45,6 +45,10 @@ def clean_data(df):
     df = df.dropna(subset=['income', 'education'])
+    # Fix: Remove negative income values (data entry errors)
+    df = df[df['income'] >= 0]
     return df

$ git add analysis.py utils.py

$ git commit -m "Fix data cleaning bug and add summary statistics"
[main a7b3c9d] Fix data cleaning bug and add summary statistics
 2 files changed, 28 insertions(+), 3 deletions(-)

$ git push origin main
Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Writing objects: 100% (4/4), 892 bytes | 892.00 KiB/s, done.
To https://github.com/username/my-project.git
   e4f5a6d..a7b3c9d  main -> main

The Status Check Habit

Get into the habit of running git status frequently. It tells you:

• Which branch you are on
• Whether you are ahead or behind the remote
• Which files have been modified
• Which files are staged for commit
• Which files are untracked (new files Git does not know about)

9.4 Creating a GitHub Repository (Step-by-Step)

Let us walk through creating a new repository on GitHub. I will explain each setting so you understand what you are choosing.

Prerequisites

• A GitHub account (free at github.com)
• Git installed on your computer (download here)

Checking if Git is Installed

Open your terminal (Terminal on Mac, Command Prompt or Git Bash on Windows) and type:

Remember: the $ at the start of command lines represents your terminal prompt — do not type it. Just type what comes after the $.

$ git --version

$ git --version
git version 2.42.0

If you see a version number (like git version 2.42.0), Git is installed. If you get an error like "command not found," you need to install Git first.

First-Time Git Setup

Before you can make commits, Git needs to know who you are. This information is attached to every commit you make. Run these commands once in your terminal (you only need to do this once per computer):

# Set your name (this appears in your commits)
$ git config --global user.name "Your Full Name"

# Set your email (use the same email as your GitHub account)
$ git config --global user.email "your.email@example.com"

# Verify your settings
$ git config --global --list

$ git config --global user.name "Jane Smith"

$ git config --global user.email "jane.smith@university.edu"

$ git config --global --list
user.name=Jane Smith
user.email=jane.smith@university.edu

# Change your name
$ git config --global user.name "New Name"

# See all your current global settings
$ git config --global --list

# Remove a setting entirely
$ git config --global --unset user.name

Step-by-Step: Create a New Repository

Go to GitHub and click "New Repository"

Click the + icon in the top-right corner of any GitHub page, then select New repository. Or go directly to github.com/new.

Choose a Repository Name

Pick a short, descriptive name using lowercase letters and hyphens:

• Good: minimum-wage-analysis, did-replication, covid-employment-study
• Avoid: my_stuff, paper1, analysis_v2_final

Add a Description (Optional but Recommended)

Write a one-line summary: "Replication code for Card & Krueger (1994) minimum wage study"

Choose Public or Private

Public	Private
Anyone can see your code	Only you and invited collaborators can see it
Good for: published papers, open-source projects, portfolios	Good for: work in progress, sensitive data, proprietary code
Free unlimited repositories	Free unlimited repositories (GitHub changed policy in 2019)

My recommendation: Start private while working, make public when ready to share or publish.

Initialize with README, .gitignore, and License

Check all three boxes. Here is what each does:

README.md: A text file that appears on your repository's main page. It should explain what your project does and how to use it. GitHub renders it beautifully with formatting.

.gitignore: A file that tells Git which files to ignore (not track). Choose a template that matches your main language:

• Python: Ignores __pycache__/, .env, venv/, *.pyc
• R: Ignores .Rhistory, .RData, .Rproj.user/

License: Specifies how others can use your code. For academic work, I recommend:

• MIT License: Very permissive - anyone can use, modify, and redistribute with attribution
• CC BY 4.0: Good for datasets and non-code content

Click "Create Repository"

Your repository is now live! GitHub will show you instructions for connecting it to your local computer.

The green "Create repository" button is at the bottom of the form (visible in the screenshot above).

The complete form is shown in the screenshot above — repository name at the top, visibility toggle, and the initialization checkboxes (README, .gitignore, License) at the bottom.

The .gitignore File Explained

The .gitignore file is crucial for research projects. It tells Git which files should never be tracked. Here is a template for economics research:

# ============================================
# .gitignore for Economics Research Projects
# ============================================

# ----- Data files (often too large or sensitive) -----
data/raw/*.csv
data/raw/*.dta
*.xlsx
*.xlsm
*.zip
*.parquet

# ----- Output (can be regenerated from code) -----
output/figures/*
output/tables/*
*.log

# ----- Python -----
__pycache__/
*.pyc
venv/
.venv/
.ipynb_checkpoints/

# ----- R -----
.Rhistory
.RData
.Rproj.user/

# ----- Stata -----
*.smcl

# ----- Secrets and credentials (NEVER commit these!) -----
.env
*credentials*
*api_key*
*secret*

# ----- OS-generated files -----
.DS_Store
Thumbs.db
Desktop.ini

# ----- IDE and editor files -----
.vscode/
.idea/

9.5 Cloning a Repository in VS Code

Cloning means downloading a complete copy of a repository from GitHub to your computer. VS Code makes this very easy.

Method 1: Clone via VS Code Interface (Recommended for Beginners)

Open VS Code

If you have a folder already open, you may want to close it first (File > Close Folder) so you start fresh.

Open the Source Control Panel

Click the Source Control icon in the left sidebar (it looks like a branch), or press Ctrl+Shift+G (Windows/Linux) or Cmd+Shift+G (Mac).

Click "Clone Repository"

You will see a button that says Clone Repository. Click it. If you do not see this button, you can also use the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and type "Git: Clone".

In the screenshot above, you can see the "Clona repository GIT..." (or "Clone Git Repository..." in English) option in the VS Code welcome screen. You can also find it in the Source Control panel (the branch-like icon in the left sidebar, third from top).

Enter the Repository URL

Go to your GitHub repository, click the green Code button, and copy the HTTPS URL. It looks like:

https://github.com/username/repository-name.git

Paste this URL into VS Code's prompt.

On your repository's GitHub page, look for the green "Code" button near the top-right of the file list. Click it, make sure the HTTPS tab is selected (not SSH), and click the clipboard icon to copy the URL. It will look like https://github.com/username/repository-name.git.

Choose Where to Save It

VS Code will ask where to save the repository on your computer. Pick a logical location like Documents/Projects/ or Documents/Research/.

A standard file browser dialog opens. Navigate to where you want to save the project (for example, Documents/Research/) and click "Select Repository Location" (or "Select as Repository Destination" depending on your OS).

Open the Repository

After cloning, VS Code will ask if you want to open the repository. Click Open.

After cloning finishes, a small notification appears in the bottom-right corner of VS Code asking "Would you like to open the cloned repository?". Click "Open" to load the project in your workspace.

Method 2: Clone via Terminal

If you prefer the command line, or if VS Code's interface is not working:

# Navigate to where you want the project
$ cd ~/Documents/Research

# Clone the repository
$ git clone https://github.com/username/repository-name.git

# Enter the project folder
$ cd repository-name

# Open in VS Code
$ code .

$ git clone https://github.com/username/repository-name.git
Cloning into 'repository-name'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (32/32), done.
remote: Total 47 (delta 12), reused 41 (delta 9), pack-reused 0
Receiving objects: 100% (47/47), 15.23 KiB | 3.81 MiB/s, done.
Resolving deltas: 100% (12/12), done.

$ cd repository-name

$ ls
README.md    analysis/    data/    output/

What Clone Actually Does

When you clone a repository, Git:

1. Creates a new folder with the repository name
2. Downloads all the files from the repository
3. Downloads the complete history (all previous commits)
4. Sets up a connection to the remote repository (called origin)
5. Checks out the default branch (usually main)

You now have a complete, fully-functional copy of the repository that you can work with offline.

VS Code's Git Integration

Once you open a Git repository in VS Code, you will notice several helpful features:

• Source Control panel: Shows changed files and lets you stage, commit, and push with clicks
• File indicators: Modified files show M, new files show U (untracked)
• Branch indicator: Bottom-left corner shows your current branch
• Gutter indicators: Green, red, and blue bars in the editor show added, removed, and modified lines
• GitLens extension: Shows who changed each line and when (if you install this extension)

In VS Code, look for these indicators: M (modified) and U (untracked) badges next to file names in the Explorer sidebar, the current branch name in the bottom-left status bar, and colored bars in the editor gutter (green = new lines, blue = modified lines).

The Source Control panel (Ctrl+Shift+G / Cmd+Shift+G) shows two sections: "Staged Changes" (files ready to commit) and "Changes" (modified but not yet staged). Above them is a text box for your commit message, and a checkmark button to commit.

9.6 The Staging Area Concept

The staging area (also called the "index") is one of Git's most confusing concepts for beginners, but it is also one of its most powerful features.

Why Not Just Commit Everything?

You might wonder: "Why not just commit all changed files automatically?" The staging area gives you precise control:

• Separate unrelated changes: You fixed a bug AND reformatted some code. Commit them separately with different messages.
• Partial file staging: You can stage just some changes in a file, not all of them.
• Review before committing: See exactly what you are about to commit before making it permanent.
• Clean history: Each commit does one thing, making it easier to find and fix issues later.

Staging Commands

# Check current status (always do this first!)
$ git status

# Stage a specific file
$ git add analysis.py

# Stage multiple specific files
$ git add analysis.py utils.py data_cleaning.py

# Stage all files in a folder
$ git add code/

# Stage ALL changed files (use carefully!)
$ git add .

# See what's staged vs. unstaged
$ git status

# See the actual staged changes (what will be committed)
$ git diff --staged

# Unstage a file (keep the changes, just don't commit them yet)
$ git restore --staged analysis.py

Staging in VS Code

VS Code makes staging visual and intuitive:

1. Open the Source Control panel (click the branch icon or Ctrl+Shift+G)
2. You will see a list of Changes - these are modified but unstaged files
3. Hover over a file and click the + icon to stage it
4. The file moves to the Staged Changes section
5. To unstage, hover and click the - icon

To stage a file in VS Code, hover over its name in the Source Control panel's "Changes" section and click the + (plus) icon that appears. To unstage, hover over the file in "Staged Changes" and click the − (minus) icon.

9.7 Committing Code: What Happens at Each Step

A commit is a permanent snapshot of your staged changes. Let us understand exactly what happens when you commit.

The Commit Process

When you run git commit:

1. Git takes a snapshot of all staged changes
2. Creates a unique identifier (the commit hash, like a7b3c9d)
3. Records metadata: your name, email, timestamp, and commit message
4. Links to the previous commit (creating the history chain)
5. Clears the staging area (but your working directory stays the same)

Writing Good Commit Messages

Commit messages are crucial. Six months from now, you (or a collaborator) will need to understand what each change did and why.

Commit Message Format

A good commit message follows this structure:

# Short summary (50 characters or less)
Add regression discontinuity analysis

# Blank line, then optional detailed explanation
# Wrap at 72 characters

This implements the RD design from Section 4.2 of the paper.
Uses the rdrobust package with triangular kernel and
MSE-optimal bandwidth selection.

Closes #12

Key principles:

• Use imperative mood: "Add feature" not "Added feature" or "Adds feature"
• Keep the first line under 50 characters (it is shown in many Git interfaces)
• Explain why, not just what (the code shows what)
• Reference issue numbers if applicable (#12 links to GitHub issue 12)

Making a Commit

# First, stage your changes
$ git add analysis.py output/table1.tex

# Commit with a message (short form)
$ git commit -m "Add baseline regression results to Table 1"

# Or open your editor for a longer message
$ git commit
# (Your editor opens, write your message, save and close)

# Shortcut: stage all tracked files AND commit in one step
$ git commit -am "Fix typo in variable name"

$ git add analysis.py output/table1.tex

$ git commit -m "Add baseline regression results to Table 1"
[main f8e9a1b] Add baseline regression results to Table 1
 2 files changed, 45 insertions(+), 3 deletions(-)
 create mode 100644 output/table1.tex

Viewing Your History

# See commit history
$ git log

# Compact one-line view (very useful!)
$ git log --oneline

# Show last 5 commits with changes
$ git log -p -5

# Visual branch graph
$ git log --oneline --graph --all

$ git log --oneline
f8e9a1b (HEAD -> main) Add baseline regression results to Table 1
a7b3c9d Fix data cleaning bug and add summary statistics
e4f5a6d Add initial analysis script
b2c3d4e Update README with project description
1a2b3c4 Initial commit

9.8 Pushing and Pulling Changes

So far, everything we have done has been local - on your computer only. To share your work or back it up, you need to sync with GitHub.

Push: Upload Your Commits

Pushing sends your local commits to the remote repository (GitHub).

# Push your commits to GitHub
$ git push origin main

# If you've set up tracking, you can just use:
$ git push

# First push of a new branch (sets up tracking)
$ git push -u origin main

$ git push origin main
Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
Delta compression using up to 8 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 1.23 KiB | 1.23 MiB/s, done.
Total 5 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), completed with 2 local objects.
To https://github.com/username/my-project.git
   a7b3c9d..f8e9a1b  main -> main

Pull: Download Changes

Pulling downloads commits from GitHub that you do not have locally. This is how you get work from collaborators or sync between computers.

# Download and merge changes from GitHub
$ git pull origin main

# Or if tracking is set up:
$ git pull

# Check if there are remote changes without downloading
$ git fetch origin
$ git status  # Will show if you're behind

$ git pull origin main
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 2), reused 0 (delta 0)
Unpacking objects: 100% (3/3), 1.12 KiB | 573.00 KiB/s, done.
From https://github.com/username/my-project
   f8e9a1b..c9d0a1b  main       -> origin/main
Updating f8e9a1b..c9d0a1b
Fast-forward
 analysis.py | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

The Push/Pull Workflow with Collaborators

This extends the daily cycle introduced in Section 9.3 with the perspective of a collaborator working in parallel:

Handling Merge Conflicts

Sometimes you and a collaborator edit the same lines of the same file. When you pull, Git cannot automatically combine the changes - this is a merge conflict.

Do not panic! Here is how to resolve it:

1. Git marks the conflict in the file with special markers:

def calculate_income(df):
<<<<<<< HEAD
    # Your version
    return df['wage'] + df['bonus']
=======
    # Collaborator's version
    return df['salary'] + df['bonus']
>>>>>>> origin/main

2. Edit the file to keep the version you want (or combine them):

def calculate_income(df):
    # Combined version - using 'salary' column with bonus
    return df['salary'] + df['bonus']

3. Remove the conflict markers (<<<<<<<, =======, >>>>>>>)
4. Stage and commit the resolved file:

$ git add analysis.py
$ git commit -m "Resolve merge conflict in income calculation"

9.9 Common Beginner Mistakes and How to Avoid Them

Everyone makes mistakes when learning Git. Here are the most common ones and how to fix (or avoid) them.

Mistake 1: Committing Sensitive Data

Mistake 2: Working on the Wrong Branch

# Stash your changes temporarily
git stash

# Switch to (or create) the correct branch
git checkout -b correct-branch

# Apply your stashed changes
git stash pop

Mistake 3: Committing Large Data Files

Mistake 4: Vague Commit Messages

Mistake 5: Not Pulling Before Pushing

Mistake 6: Panic-Deleting the .git Folder

Mistake 7: Using git add . Without Checking

Quick Recovery Commands

# Unstage a file (keep changes, just don't commit yet)
$ git restore --staged filename.py

# Discard changes to a file (WARNING: loses your edits!)
$ git restore filename.py

# Undo the last commit but keep changes staged
$ git reset --soft HEAD~1

# Undo the last commit, unstage changes but keep edits
$ git reset HEAD~1

# Undo the last commit AND discard all changes (DANGEROUS!)
$ git reset --hard HEAD~1

# See what you can recover (reflog saves you!)
$ git reflog

9.10 Environment Variables, .env Files, and GitHub Secrets

As your projects grow, you will encounter situations where your code needs sensitive information — API keys, database passwords, or file paths that differ between machines. Hardcoding these values into your scripts is a security risk and makes collaboration harder. The standard solution is a .env file.

What is a .env File?

A .env file is a plain text file named exactly .env (note the dot — it is a hidden file) that stores configuration values your code needs but that should not be in your source code. It sits in your project's root directory and contains simple key-value pairs:

API_KEY=sk-abc123xyz
DATABASE_URL=postgresql://user:pass@localhost/mydb
DATA_PATH=/Users/giulia/data/raw/

How to Create a .env File

Create a file literally named .env in your project root (no file extension):

• In VS Code: File → New File, then name it .env
• In terminal (Mac/Linux): touch .env
• In terminal (Windows): echo. > .env

How Your Code Reads .env Variables

# First install the package: pip install python-dotenv
from dotenv import load_dotenv
import os

# Load variables from .env into the environment
load_dotenv()

# Access a variable
api_key = os.getenv("API_KEY")
data_path = os.getenv("DATA_PATH")

# Install the package: install.packages("dotenv")
library(dotenv)

# Load variables from .env into the environment
load_dot_env()

# Access a variable
api_key <- Sys.getenv("API_KEY")
data_path <- Sys.getenv("DATA_PATH")

* Stata does not have native .env support.
* Instead, create a config.do file in your project root:

* --- config.do ---
global data_path "/Users/giulia/data/raw/"
global api_key "sk-abc123xyz"

* --- In your analysis script ---
do "config.do"
use "${data_path}survey_data.dta", clear

# Add this line to your .gitignore file
.env
config.do

# Copy this file to .env and fill in your values
API_KEY=your_api_key_here
DATABASE_URL=your_database_url_here
DATA_PATH=/path/to/your/local/data/

GitHub Secrets (for GitHub Actions)

If you use GitHub Actions (automated workflows that run in the cloud), you may need API keys or credentials there too. You cannot use a .env file because it is not committed to your repo. Instead, GitHub provides Secrets — encrypted values stored securely on GitHub's servers.

# Inside a GitHub Actions workflow file
env:
  API_KEY: ${{ secrets.MY_API_KEY }}

9.11 Essential Git Commands Summary

Here is a quick reference of the commands covered in this module. Print this out or bookmark it!

Setup and Configuration

Daily Workflow

Syncing with GitHub

Branching

Undoing Things

9.12 Further Resources

Interactive Tutorials

• Learn Git Branching - Visual, interactive tutorial for understanding branches
• Oh My Git! - A game for learning Git
• Git Immersion - Guided tour through Git fundamentals

Documentation

• Pro Git Book - The definitive free Git book (Chapters 1-3 are essential)
• GitHub Docs: Getting Started - Official GitHub documentation
• Git Cheat Sheet (PDF) - Printable reference from GitHub

For Economists and Researchers

• Git for Data Scientists - Git workflows tailored for data work
• AEA Data and Code Availability Policy - Journal requirements for code
• Gentzkow, M., & Shapiro, J. M. (2014). Code and Data for the Social Sciences - Best practices guide

Video Tutorials

• Git and GitHub for Beginners (freeCodeCamp, ~60 min)
• Git Tutorial for Beginners (Traversy Media, ~30 min)