1. Git basics¶
1.1 The idea¶
The blocks labelled "What you should see" in this guide come from running these commands in a test folder. Your commit codes, dates and folder names will differ, ... marks a shortened folder path, and very long output is trimmed.
Git is a program that records versions of a folder. Each saved version, called a commit, stores what changed, who changed it, when and why. Nothing committed is lost, so you never need files such as final_v2_really_final.docx.
Install it from git-scm.com, then tell it who you are, once:
git config --global user.name "Your Name"
git config --global user.email "you@example.org"
1.2 The everyday cycle¶
git init -b main # start tracking this folder, once, on a branch called main
git status # what has changed?
git diff # show the changes, line by line
git add results.txt # choose what goes in the next version
git commit -m "Correct the mean" # save that version, with a reason
git log --oneline # list the versions
What you should see
$ git init -b main
Initialized empty Git repository in .../project/.git/
$ git status
On branch main
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
notes.txt
results.txt
nothing added to commit but untracked files present (use "git add" to track)
$ git add results.txt
$ git commit -m "First results"
[main (root-commit) 4f2d1b0] First results
1 file changed, 1 insertion(+)
create mode 100644 results.txt
Now change the number in results.txt and look again. In git status --short, M means modified and ?? means not tracked. In git diff, a line starting - was removed and a line starting + was added.
What you should see
$ git status --short
M results.txt
?? notes.txt
$ git diff
diff --git a/results.txt b/results.txt
index 62b900e..de5c1f9 100644
--- a/results.txt
+++ b/results.txt
@@ -1 +1 @@
-The mean is 10.
+The mean is 12.
$ git add results.txt
$ git commit -m "Correct the mean"
[main 2f4cdbe] Correct the mean
1 file changed, 1 insertion(+), 1 deletion(-)
$ git log --oneline
2f4cdbe Correct the mean
4f2d1b0 First results
Without -b main, this version of Git names the first branch master and prints a long hint about it. The rest of this guide uses main.
The add step exists so that one commit can hold one logical change, even if you changed other files too.
1.3 Try it safely¶
This script makes a new folder and goes through the whole cycle. Read it, then run it.
practice.sh
#!/bin/bash
# A safe practice run of everyday Git, in a new folder. Run: bash practice.sh
set -e
mkdir git-practice && cd git-practice
git init -q -b main
git config user.name "A Student"
git config user.email "student@example.org"
# Save a first version
echo "The mean is 10." > results.txt
git add results.txt
git commit -q -m "First results"
# Change it and see exactly what changed
echo "The mean is 12." > results.txt
git diff --stat
git add results.txt
git commit -q -m "Correct the mean"
# Name this version
git tag -a sent-to-supervisor -m "The version I sent"
# Try an idea safely on a branch, then bring it back
git switch -q -c idea
echo "The median is 11." >> results.txt
git add results.txt
git commit -q -m "Add the median"
git switch -q main
git merge -q idea
# Undo the last change, keeping the history
git revert --no-edit HEAD
git log --oneline
cat results.txt
What you should see
results.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
[main ab8a9f9] Revert "Add the median"
Date: Sun Nov 1 16:26:34 2026 +0000
1 file changed, 1 deletion(-)
ab8a9f9 Revert "Add the median"
bd9ec39 Add the median
6f32cdc Correct the mean
8c59d4e First results
The mean is 12.
The last line matters: the median has gone from the file, yet all four versions are still in the history.
1.4 What to track¶
Track what you write by hand: text, code and small inputs. Don't track what can be regenerated, large data, or anything secret. A file called .gitignore lists what to skip:
__pycache__/
*.log
build/
data/raw/
.env
With that file in place, and run.log, .env and build/a.pdf in the folder, Git no longer mentions them:
What you should see
$ git status --short
?? .gitignore
?? notes.txt
1.5 Good commit messages¶
Write what changed and why, briefly, such as Correct the living-wage year. Commit often, in small steps, so that each can be understood or undone by itself.