Git & GitHub for Ecologists

Almost every model and pipeline you'll touch in this course lives on GitHub. This tutorial walks you, slowly, from "I've never used git" to "I can clone a repo, contribute a fix, and keep my own work versioned."

1. Two things that are easy to confuse

You can use git without GitHub (local version control). You generally cannot use GitHub without git (or one of its GUI front-ends).

2. Install git and make a GitHub account

macOS

# git ships with Xcode command-line tools; trigger the install:
xcode-select --install

# Or via Homebrew (gets the newest version):
brew install git

git --version
# git version 2.45.x

Windows

# PowerShell:
winget install Git.Git

# Restart your terminal, then:
git --version

On Windows, the installer also gives you Git Bash, a UNIX-style terminal that works the same way as macOS/Linux terminals. We recommend using Git Bash (or Windows Terminal with PowerShell, but Git Bash is friendlier for following along with tutorials).

Make a GitHub account

Go to github.com/signup. Use your university email so you can later claim a free GitHub Student Developer Pack (it's worth it — free private repos and free CI minutes).

Tell git who you are (one time, per machine)

git config --global user.name  "Your Name"
git config --global user.email "you@university.edu"
git config --global init.defaultBranch main

3. The two-minute mental model

A git repository ("repo") is a folder on your computer with a hidden .git/ subfolder where git stores history. Three states a file can be in:

1. Working directory — your files as you see them in Finder/Explorer.
2. Staging area — files you've told git "I want these in my next snapshot". Add with git add.
3. Committed — permanent snapshot stored in .git/ with a message. Save with git commit -m "...".

A snapshot of all three states — what's changed, what's staged, what's already committed — is shown by git status. You will run git status constantly. It's the most useful git command.

4. Your first repo (10 minutes, all local)

# Make a folder and turn it into a git repo
mkdir my_first_repo
cd my_first_repo
git init

# Create a file
echo "# My notes" > README.md
git status
#   On branch main
#   No commits yet
#   Untracked files: README.md

# Stage and commit
git add README.md
git commit -m "initial commit: add README"

# Make a change
echo "Day 1: installed Python." >> README.md
git status      # shows README.md as "modified"
git diff        # shows the actual line that changed
git add README.md
git commit -m "log day 1"

# See your history
git log --oneline

5. Cloning someone else's repo

Almost everything you do in this course starts by cloning a public repo from GitHub. To clone Zach Ruff's PNW-Cnet Python package:

cd ~/research                                            # wherever you keep code
git clone https://github.com/zjruff/pycnet-audio.git
cd pycnet-audio
ls

You now have an exact copy of the repo's main branch on your laptop, including its full history. To pull in any new commits the author has made since you cloned:

git pull

6. Reading a GitHub repo well (don't skip this)

Before you run anyone's code, spend five minutes scanning the repo. Look at, in this order:

1. README.md — what is this, who is it for, how do I install and run it.
2. LICENSE — can I use this in my work? MIT/Apache/BSD = yes, GPL = yes with conditions, no LICENSE file = legally ambiguous, be careful.
3. The Issues tab — what's broken, what's coming, has anyone hit the bug you're about to hit?
4. The "About" sidebar and recent commits — is this actively maintained? A repo last touched in 2019 may still be great, but you should know.
5. requirements.txt / environment.yml / pyproject.toml — what versions of what packages does it need? Mismatched versions are the #1 cause of "it doesn't work for me".

7. Your second repo — pushing to GitHub

Now make your own repo on GitHub for your course work.

Create the empty repo on GitHub

1. Go to github.com/new.
2. Name: aiecol-coursework.
3. Visibility: Private (you can flip to public later).
4. Do NOT check "initialize with README" — you already have one locally.
5. Click Create repository.

Link your local repo to GitHub and push

GitHub will show you the exact commands. They look like:

cd my_first_repo
git remote add origin https://github.com/yourname/aiecol-coursework.git
git branch -M main
git push -u origin main

The first git push will prompt you for authentication. GitHub does not accept your password from the command line anymore. You have two good options:

Auth option A — GitHub CLI (easiest)

brew install gh                  # macOS
winget install GitHub.cli        # Windows
gh auth login
# Pick HTTPS, then "Login with a web browser", paste the one-time code.

After this, git push "just works" forever on this machine.

Auth option B — SSH key

ssh-keygen -t ed25519 -C "you@university.edu"
# Press Enter for default location; set a passphrase if you want.

# Print the PUBLIC key (the .pub file):
cat ~/.ssh/id_ed25519.pub
# Copy the line that prints.

On GitHub: Settings → SSH and GPG keys → New SSH key, paste, save.

Then change your remote URL to the SSH form:

git remote set-url origin git@github.com:yourname/aiecol-coursework.git
git push

8. The everyday loop

Once your repo is on GitHub, this is what each working session looks like:

cd aiecol-coursework
git pull                      # grab anything you pushed from another machine

# ... do work ...

git status                    # see what changed
git diff                      # see the actual lines that changed
git add lab3/detect.py        # stage the files you want to commit
git commit -m "lab 3: lower MD threshold to 0.2 and rerun"

git push                      # send your commits to GitHub

9. Branches (when you want to try something without breaking what works)

# Start a new branch off of main
git checkout -b try-yolov8m

# ...edit, train, evaluate...
git add -A
git commit -m "try yolov8m, larger model"

# It didn't help. Throw it away:
git checkout main
git branch -D try-yolov8m

# Or it helped. Bring it into main:
git checkout main
git merge try-yolov8m
git push

10. Forking and pull requests — how you contribute to someone else's repo

You found a typo in the pycnet-audio README. Here's how to fix it.

1. On GitHub, go to github.com/zjruff/pycnet-audio. Click Fork (top right). You now have your own copy under your account.
2. Clone your fork:

   git clone https://github.com/yourname/pycnet-audio.git
   cd pycnet-audio

3. Make a branch, edit, commit, push:

   git checkout -b fix-readme-typo
   # edit README.md
   git add README.md
   git commit -m "docs: fix typo in install instructions"
   git push -u origin fix-readme-typo

4. On GitHub your fork now has a banner saying "fix-readme-typo had recent pushes — Compare & pull request". Click it. Write a one-paragraph description. Submit.
5. The maintainer reviews. If they merge, your fix is in the canonical repo. If they ask for changes, push more commits to the same branch and they'll appear in the PR.

This is how almost every open-source ecology tool gets improved.

11. A .gitignore for ecology / ML projects

You do not want to push 8 GB of camera-trap images, model weights, or your Anthropic API key to GitHub. Create a file called .gitignore at the root of your repo before your first push:

# Data — never put raw datasets in git
data/
*.JPG
*.jpg
*.wav
*.mp3
*.npy
*.pt
*.h5
*.onnx
runs/

# Python build / cache
__pycache__/
*.pyc
.venv/
env/

# Notebooks: keep clean by stripping outputs before commit (see nbstripout)
.ipynb_checkpoints/

# OS junk
.DS_Store
Thumbs.db

# Secrets
.env
*.key
.claude/credentials.json

12. When git scares you

Git has a famously bad CLI for a few specific situations. Some quick rescue commands:

When in doubt: git status first, then ask Claude Code to explain what it sees (paste the output verbatim). Claude is excellent at git triage.

13. Where to go next

• Pro Git — free book, the authoritative reference.
• GitHub Learning Lab — interactive tutorials.
• GitHub Student Developer Pack — free pro features and partner credits while you're a student.
• This course's Claude Code + GitHub workflow section — how to drive all of this from Claude Code instead of the bare CLI.