Put Your Project Under Version Control

Core path: 35 minutes

Git is most useful when history tells a story.

One giant commit named finished tells almost no story at all.

In this lesson you will take a working Python project and build a local Git history around deliberate changes: documentation, a feature, another feature, a bug, and the repair.

A managed remote is optional. The local repository evidence is required.

Inspect before you initialize or change anything

From the project root:

git status

If the folder is already a repository, read the output before running setup commands you do not need.

If your classroom workflow requires initialization, follow that setup and then inspect status again.

Create or improve README.md, then inspect:

git diff

Stage only the intended file:

git add README.md
git status

Then commit:

git commit -m "Document player roster project"

The useful sequence is:

change
  ↓
inspect
  ↓
stage intentionally
  ↓
inspect staged state
  ↓
commit

Not:

change a bunch of things
  ↓
git add .
  ↓
hope

Add one feature per checkpoint

Add a display function to main.py.

Run the program.

Then:

git diff
git status

If the diff contains only the feature you intended, stage and commit it.

Next, add player search and repeat the process.

A reasonable history might become:

4fd72c1 Add player search
9a18d03 Add roster display function
5ce911e Document player roster project

The hashes will be different on your machine. The story should still be readable.

Make and repair one controlled bug

Change the search so it becomes case-sensitive even though the requirement says search should ignore capitalization.

Capture the failing behavior.

Then inspect:

git diff

Repair the bug, rerun the test, and make a focused fix commit.

The final history should make it possible to identify when the fix happened.

Build .gitignore for files that do not belong in history

Create:

__pycache__/
*.pyc
.venv/
temporary.log

Create temporary.log, then run:

git status

The ignored file should not appear as a normal untracked file.

A .gitignore rule does not delete a file and it does not remove something Git is already tracking. It tells Git which currently untracked paths should normally stay outside version control.

Read the history you created

Run:

git log --oneline

Ask whether another developer could infer the order of your work from the commit messages.

Then inspect the current state:

git status

A clean status is useful evidence that your working tree matches the current committed state.

A dirty status is not automatically bad, but you should be able to explain exactly why it is dirty.

Optional managed remote

Only if your class provides one:

git remote -v

Inspect the configured destination before pushing.

Then use the classroom workflow to push and verify the expected commits remotely.

Do not publish credentials, secrets, personal information, student records, or private course material.

If no managed remote exists, git log --oneline plus git status is enough for the required evidence.

Success evidence

Your project should show:

• at least four meaningful commits;
• at least one diff inspected before staging;
• one intentionally introduced bug and verified repair;
• a .gitignore rule you actually proved;
• readable commit messages; and
• a final git status you can explain.

Version control is not a backup button with better branding. It is a record of deliberate state changes.