Git and GitHub
Introduction to Git and GitHub
Before diving into the commands, it is helpful to distinguish between the two tools:
- Git is the underlying software that runs locally on your computer. It acts as a time machine for your codebase, recording a history of every change you make to your files.
- GitHub is an online hosting platform (like Dropbox or Google Drive, but for code) that stores your Git repositories in the cloud, allowing you to back up your work, share it with the public, or collaborate seamlessly with external researchers.
Recommended Quick Starts:
1. Why You Should Use Version Control
If you have ever had a directory filled with files named script_final.py, script_final_real.py, and script_tweak_v2.py, you already understand the need for version control.
The Solo Disaster Imagine you have spent three weeks perfecting a script that implements an optimization procedure for a new estimator. Right before a meeting with your advisor, you decide to make a "quick tweak" to the loss function. Suddenly, the script throws a tensor dimension error, the data pipeline crashes, and you cannot remember exactly which lines you modified. With Git, you can simply run a command to see exactly what changed, or instantly revert the file back to its last working state.
The Collaboration Headache Suppose you and an external committee member are both working on the same codebase. Without version control, you might email zip files back and forth. If you both edit the main optimization script at the same time, someone's work is going to be overwritten and lost. Git and GitHub solve this by intelligently merging different contributors' changes line-by-line and highlighting any conflicts before they break the project.
2. Local Git Operations
To start using git for version control on your own computer, you will use the command line to initialize a repository and make "commits" (snapshots of your project).
Step 1: Initialize a Repository
Navigate to your project folder in the terminal and tell Git to start tracking it.
git init
Step 2: Stage Your Changes
Before taking a snapshot, you must tell Git which modified files you want to include.
git add my_script.py
- (Tip: Use
git add .to stage all modified files in the directory)*
Step 3: Commit the Changes
Save the snapshot with a brief, descriptive message explaining what you did.
git commit -m "Fix tensor broadcasting bug in spatial model"
Helpful Commands: Use git status to see which files are modified but not yet committed, and git log to view your entire commit history.
3. Interfacing with GitHub
Once your code is tracked locally, you will likely want to back it up or share it via GitHub.
Uploading a Local Repo to GitHub
- Go to GitHub and click the New button to create a new repository.
- Give it a name and description, but do not initialize it with a README (since you already have local files).
- Copy the URL provided by GitHub.
- In your local terminal, link your computer to the GitHub server and upload (push) your code:
git remote add origin https://github.com/your-username/your-repo.git git push -u origin main
Downloading an Existing Repo (Cloning)
If you want to download a project that already exists on GitHub (either your own from a different computer, or someone else's public codebase), you do not need to download a zip file. Instead, clone it:
git clone https://github.com/username/repository-name.git
This downloads the code and the entire Git history, keeping the link to the GitHub server intact so you can easily pull future updates.
