This guide will help you manage your research code, notes, and small datasets using Git (the tool on your computer) and GitHub (the cloud storage and collaboration platform).

The official tutorial provides additional details.

What is it?

Git is a version control system that tracks changes in files. You can save a snapshot of your research project (Stata code, LaTex files, Word docs, Python code etc.), implement changes to your project, and decide to keep those changes or go back to your previous snapshot. As you update your project, Git maintains a full history of updates.

GitHub is a cloud-based platform where you store your work. When you upload files to GitHub, you store them in a "Git repository." This means that when you make changes to your files in GitHub, Git will automatically start to track and manage your changes.

 
Most people work on their files locally (on their own computer), then continually sync these local changes—and all the related Git data—with their repository on GitHub.

Why use Git for Research?

1. Version Control: Think of Git as a time machine for your research project. Whether you are writing code to do data analysis, collecting notes on academic articles, or drafting your own research paper, your files evolve over time and it is extremely useful to systematically track those changes. If some changes make things worse, you can always revert to a previous version of your project.
2. Safety: Your work is backed up on GitHub. If your laptop dies, your research survives.
3. Collaboration: Multiple researchers can work on the same paper or code simultaneously without overwriting each other. For example, your advisor can view your progress as it happens, and provide useful feedback based on the full history of your work.

Key Vocabulary

To use Git, you must internalize these five terms:

1. Repository (Repo): Your project folder. It contains your data scripts, notes, and a hidden .git folder that stores your history.
2. Clone: Copying a project from GitHub to your computer for the first time.
3. Commit: A "save point" in your work.
4. Push: Sending your local "save points" up to GitHub.
5. Pull: Grabbing the latest "save points" from GitHub to your computer (essential if you work on multiple machines).

How to start working on GitHub?

A detailed tutorial is available on GitHub, but here are the essential steps:

1. Create an account at https://github.com/
2. Create a repository (folder) and create a file inside that repository
3. Edit the file, commit your edits, and push the edits to GitHub

Your local repo is simply the project folder that lives on your computer locally - you open/edit it in VS Code, Jupyter, Obsidian, LaTeX, etc. For example, your folder structure on your local machine may look something like this:

Documents/
  └── websites/
      └── academic-site/      <- this is your local repo
          ├── _config.yml
          ├── _toc.yml
          ├── lectures/
          ├── empirical_facts/
          ├── data/
          └── .git/           <- hidden folder with version history

The root repository is wherever the .git folder lives. In the example above, /academic-site is the root repository. You locally edit any files contained within the root repository as normal, Git just tracks the changes. Also, if you clone a repository, GitHub creates a new folder on your computer with all the files and their history.

Your GitHub repo (remote) is the the copy of your project that lives in the cloud. Whenever you push edits done locally, those new version files are sent to GitHub.

The Daily Research Workflow

Once you have your project set up, you will follow this loop every time you work. I include some functional details here so you can practice updating a work project and pushing the edits to GitHub.

Step 1: Sync to Start

Before you type a single line of code, make sure your computer has the latest version of the project.

Navigate to the root repository of your Git using File Explorer (for Windows), right-click and open Git Bash. (Sometimes you may have to select "Show more options" after right-clicking.) This open up a Git terminal where you can input commands.

To pull the latest version of your project from GitHub type:

git pull origin main

Step 2: Work

Edit your Python scripts, Jupyter Notebooks, or LaTeX files as usual. All of this is being done locally on your machine.

Step 3: Record Your Progress (The "Add & Commit")

Once you've reached a stopping point (e.g., you finished a specific table or fixed a bug), type of the following in Git Bash:

# Check what you changed
git status

# Add specific files
git add analysis_script.py

# Or add everything you changed
git add .

# Save the snapshot with a descriptive message
git commit -m "Added robust standard errors to baseline model"

Step 4: Sync to End

Send your work to the cloud so it's safe and available elsewhere.

git push origin main

I recommend using the command line interface via Git Bash. You get a clear understanding of the workflow and how your updates are being tracked over time. However, if you prefer you can use GitHub Desktop with provides a simple user interface with a point-and-click option for Git. I recommend starting with the command line interface, and if you feel it's cumbersome to typing commands, you can layer GitHub Desktop on top later for convenience.

Branches

The final main architecture of GitHub are branches. Branches are alternate timelines of your project. By default, our repository has one branch named main that is considered to be the definitive branch. You can create additional branches off of main in your repository.

Branching is helpful when you want to add new features to a project without changing the main source of code. The work done on different branches will not show up on the main branch until you merge it, which we will cover later in this guide. You can use branches to experiment and make edits before committing them to main.

For most solo work, you can stick with using only the main branch. If, however, your project becomes more complex and warrants experimenting with substantially different trajectories, or you are collaborating with others, consider using branches.