Part 1: Git Basics¶
Note
Part 1 of 4. This part uses the cookiecutter-git-workshop-basics repository for its hands-on tasks. Make sure you’ve completed Prerequisites first.
See also
A condensed slide deck of this part is available for presenting: Part 1 slides (see Presentation Slides).
Why version control at all?¶
Before touching any commands, it’s worth being clear about the problem git
actually solves. Without version control, “keeping track of changes” usually
means one of two bad options: editing a single shared file and hoping nobody
overwrites someone else’s work, or manually copying folders around
(report_final.py, report_final_v2.py,
report_final_v2_ACTUALLY_FINAL.py…). Neither scales past one person,
and neither gives you a real history of why something changed.
Git solves this by recording your project as a sequence of commits — snapshots of the entire project at a point in time, each with a message explaining what changed and why, each linked to the commit before it. That chain of commits is your project’s history: you can look back at any past state, see exactly what changed between any two points, and — critically — several people can work on independent copies of that history at once and combine their work back together in a structured way.
A repository (or “repo”) is that history plus the current files. It exists in two places at once: a local repository on your own machine, and a remote repository hosted on a server (GitLab, in this workshop) that acts as the shared point of truth everyone synchronizes with. Git is a distributed version control system, meaning your local copy has the full history too, not just a checkout of the current files — you can commit, browse history, and work fully offline, and only need the network when you actually want to synchronize with the remote.
If any of these words (repository, commit, branch, remote, origin, upstream, HEAD) are unfamiliar as you read on, the Glossary has a short definition for each — it’s worth skimming once before you start.
The core workflow¶
Almost everything you’ll do in this workshop is one repeated cycle, shown below, and explained step by step afterwards. It’s the same cycle professional software teams use, just with training wheels (you’ll be reviewing your own work at first, instead of a colleague’s).
1. Update Local
│
▼
2. Create Branch
│
▼
3. Add Commits
│
▼
4. Push Branch
│
▼
5. Merge Request
│
▼
6. Discussion
│
▼
7. Merge Branch
│
└──────► back to 1. Update Local
1. Update Local¶
Before starting any new piece of work, make sure your local main branch
matches the remote’s main branch. If you skip this, you risk building
your new feature on top of an outdated version of the project, which makes
merging harder later and can hide the fact that someone else already
changed the code you’re about to touch.
In PyCharm: click the branch indicator in the bottom-right corner (next to
the padlock icon), select main, choose Checkout, then use the
Git → Pull menu to fetch and merge in the latest remote commits.
2. Create Branch¶
Never make changes directly on main. Instead, create a new branch —
recall from the glossary that a branch is just a movable pointer to a
commit — starting from your freshly updated main. Working on a branch
means your in-progress, possibly-broken changes are completely isolated
from the stable main branch that everyone else relies on. If your idea
doesn’t work out, you delete the branch and main was never affected.
In PyCharm: click the branch indicator, choose New Branch, and give it a
short name describing what you’re about to do (e.g. document-thumbnail-cmd).
3. Add Commits¶
Now actually make your change — edit a file, add a file, whatever your task
requires — and turn it into one or more commits. A good commit is small and
focused: “document the thumbnail command” is a good commit; “assorted
changes” covering five unrelated things is not. Small commits are easier to
review, easier to understand months later via git log, and easier to
undo individually if one of them turns out to be wrong.
In PyCharm, creating a new file prompts “should Git track this file?” — answering Add stages it (recall: the staging area is the intermediate step where you assemble exactly what belongs in the next commit). Existing tracked files are staged automatically when you commit through PyCharm’s commit dialog, where you also write the commit message.
4. Push Branch¶
Your commits so far only exist on your own machine. Push the branch to upload it to the remote server, creating (or updating) an identical copy of your branch there. This is also what makes your work visible/reviewable by others, and is a good habit even when working solo — it’s a backup of your work-in-progress that survives a dead laptop.
In PyCharm: Git → Push from the menu bar.
5. Merge Request¶
With your branch pushed, open a merge request (GitLab’s term; GitHub
calls the same thing a “pull request”) on the server: a request to merge
your branch into main, together with a description of what changed and
why, and a reviewer. Even solo, writing this description is valuable — it
forces you to explain your own change, which often surfaces problems before
anyone else even looks at it.
6. Discussion¶
A reviewer (a colleague, or in this solo workshop, yourself) reads the diff and comments. This is code review, and its point isn’t to catch every possible issue — it’s a second pair of eyes that catches issues you’re too close to your own code to see, and a natural point to discuss why a change was made, not just what changed. If review turns up something to fix, you go back to step 3, add more commits to the same branch, and push again — the merge request updates automatically.
7. Merge Branch¶
Once the merge request is approved, click Merge. Your branch’s commits
are now part of main on the remote, and everyone else will get them the
next time they update their own local main (back to step 1). This is
exactly the cycle you’ll repeat for every task below, and for every feature
you ever build using git.
See also
GitHub’s guide to this workflow covers the same cycle from a slightly different angle, if you’d like a second explanation.