Git basics

A history you can go back to

Git records the history of a project as a series of commits: snapshots of all tracked files, each with an author, a time and a message. With it you can see what changed and why, try an idea without fear and return to a version that worked. A folder under Git's control is a repository. Quant work leans on this heavily: a result is only trustworthy if you can say exactly which version of the code produced it.

# Start tracking a project (once)
git init

# See what changed, stage it, record it
git status
git add main.py README.md
git commit -m "Add the first backtest loop"

# Look back
git log --oneline
git diff                      # changes not yet staged

Three places a change lives

A change moves through three areas. You edit files in the working tree. git add copies the chosen changes to the staging area (the next snapshot, being prepared). git commit records the staged snapshot in the repository history. This lets you commit only the related changes together, even if you edited many files. git status shows each file in its area: modified, staged, or untracked (new and not yet known to Git).

# git status --porcelain prints two status letters, a space, then the path
status = """ M main.py
A  notes.md
?? scratch.txt
D  old.py"""

for line in status.splitlines():
    code, path = line[:2], line[3:]
    print(repr(code), path)
# ' M' main.py     (modified, not staged)
# 'A ' notes.md    (new, staged)
# '??' scratch.txt (untracked)
# 'D ' old.py      (deleted, staged)

Branches

A branch is a movable name for a line of commits. Create one for each idea or fix (git switch -c fee-model), commit on it freely, and when it works bring it back into the main line with git merge (usually from the main branch). Branch names can contain letters, digits, -, _, / and ., but no spaces and none of ~ ^ : ? * [ \, and they cannot start or end with / or end with .. Git tells you about conflicts when two branches changed the same lines, and you resolve them by hand.

# Try an idea on its own branch, then bring it back
git switch -c fee-model
git commit -am "Use tiered fees"
git switch main
git merge fee-model

# List branches (the current one has a star)
git branch

What to leave out, and how to undo

A .gitignore file lists patterns Git should not track: .venv/ (a folder, written with a trailing slash), *.log (any file matching a wildcard), secrets.env. Keep out virtual environments, caches, large data files and above all secrets such as API keys: anything committed stays in the history even if you delete it later. To undo, git restore file throws away uncommitted edits to a file, and git revert <commit> adds a new commit that cancels an old one, which is safe on shared branches. git push and git pull exchange commits with a remote copy such as one on GitHub.

# .gitignore
.venv/
__pycache__/
*.log
secrets.env

# Undo safely
git restore main.py            # drop uncommitted edits to one file
git revert 3f2a9c1             # new commit that cancels an old one

# Share
git push origin main
git pull

• git init, git status, git add, git commit -m "...", git log --oneline.
• Branch per idea: git switch -c name, then git merge.
• Use .gitignore for .venv/, caches, data and secrets; undo with restore or revert.

Next up: Jupyter notebooks, for exploring data interactively, and how to keep them tidy under Git.

Lab · what's graded

• Sort the files in a git status report with parse_status25 pts
• Read a git log --oneline listing with parse_log25 pts
• Check a branch name against Git's rules with is_valid_branch_name25 pts
• Apply a .gitignore to a list of files with not_ignored25 pts