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.