Prerequisites¶
Before starting Part 1, install the following tools once and get comfortable with the basics on this page. Every later part of the curriculum assumes you can already open a terminal, move around in it, and create a virtual environment — so if you’ve never used a command line before, take your time here; it pays off immediately in every part that follows.
Tip
If a command fails with an error message, don’t guess — check Troubleshooting. It lists the ten or so errors that almost everyone hits at least once, what causes them, and how to fix them.
Note
The examples on this page show Windows commands first, since that’s what most students use, followed by the macOS/Linux equivalent. Use whichever matches your machine.
Python¶
Install a current Python (3.10 or newer) from python.org/downloads.
Important
Windows users: on the first screen of the installer, tick the
checkbox “Add python.exe to PATH” at the bottom before clicking
Install. If you miss it, Windows won’t be able to find Python when you
type python in a terminal, and almost every command in this
curriculum will fail with 'python' is not recognized. If that
happens, just run the installer again and choose Modify.
Once it’s installed, verify it — open a terminal (the next section explains how) and type:
python --version
python3 --version # macOS/Linux
You should see something like Python 3.12.4. If you instead get an
error, or the Microsoft Store opens, see Troubleshooting.
Note
On Windows, Python can be called in three ways: python, py (the
“Python launcher”, installed alongside it), and python3 (which
usually does not work and opens the Microsoft Store instead). This
curriculum uses python for Windows and python3 for macOS/Linux.
If python doesn’t work for you on Windows, try py — everywhere
this page shows python, py will do the same job.
Using a terminal¶
A terminal (also called a shell or command line) is a text-based way to give your computer instructions: instead of clicking icons, you type a command and press Enter. Every task in this curriculum that says “run” or “install” some command means: type it into a terminal.
How to open one:
Windows: press the Start button, type “PowerShell”, press Enter. (Git, installed below, also comes with “Git Bash”, which behaves like the macOS/Linux terminals and which some people prefer.)
macOS: press
Cmd+Space, type “Terminal”, press Enter.Linux: open your desktop’s terminal application (e.g. GNOME Terminal or Konsole), usually listed under “System” or “Utilities”.
Once open, you’ll see a prompt: some text (often your username and current folder) followed by a cursor. That’s where you type commands.
Later on, once you have a project open in PyCharm, you can use PyCharm’s built-in terminal instead — View → Tool Windows → Terminal, or the “Terminal” tab along the bottom edge. It’s convenient because it already starts inside your project folder. For the very first commands you’ll run (installing tools, generating your first project) there is no project yet, so use your operating system’s terminal from the list above.
Creating files and folders¶
Several tasks ask you to create a file with an exact name — some of which
start with a dot (.gitignore, .readthedocs.yaml, .gitlab-ci.yml)
or have an unusual extension (pyproject.toml, tox.ini). The reliable
way to do this is inside PyCharm:
New file: right-click the folder in PyCharm’s project tree (left-hand panel) → New → File → type the complete filename → Enter.
New folder: right-click → New → Directory.
Warning
Type the whole name, including any leading dot and the extension —
.gitignore, not gitignore. Creating these in Windows Explorer
instead is risky: Explorer hides known file extensions by default, so
“.gitignore” silently becomes .gitignore.txt and won’t work.
PyCharm doesn’t do this, which is why it’s the recommended route.
A file’s extension is the part after the last dot (.py for Python
code, .md for Markdown, .rst for reStructuredText, .toml/.ini/
.yaml for configuration). It tells tools what kind of file it is, so
getting it exactly right matters.
Virtual environments¶
A virtual environment (venv) is an isolated copy of Python plus whatever packages you install into it, kept separate from your system Python and from your other projects. Without one, packages installed for one exercise can silently conflict with packages needed by another. You’ll create one for every package you build in this course, right after generating or cloning it — the venv itself is not stored in git (it’s regenerated locally, not tracked).
Putting the last few sections together, creating and activating a venv for a project looks like this in full:
cd %USERPROFILE%\projects\git_workshop_basic # 1. move into the project folder
python -m venv .venv # 2. create the environment (once)
.venv\Scripts\Activate.ps1 # 3. activate it (PowerShell)
cd ~/projects/git_workshop_basic # 1. move into the project folder
python3 -m venv .venv # 2. create the environment (once)
source .venv/bin/activate # 3. activate it (macOS/Linux)
Step 2 (creating it) only happens once per project. Step 3 (activating it) happens every time you open a fresh terminal to work on that project.
How do you know it worked? Your prompt gains a (.venv) prefix:
(.venv) PS C:\Users\you\projects\git_workshop_basic>
If it’s not there, the environment is not active, and any pip install
you run will go to the wrong place. To leave the environment again, type
deactivate.
Warning
Windows/PowerShell: step 3 may fail with “running scripts is disabled on this system”. This is a Windows security default, not a mistake on your part. Fix it for the current terminal window with:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
then run the activate command again. See Troubleshooting for the alternatives (Command Prompt or Git Bash) if you’d rather not do that.
Telling PyCharm about your environment¶
PyCharm runs code with whichever Python interpreter it is configured to
use, which isn’t automatically the .venv you just made. If they differ,
you’ll see the confusing situation where an import works in the terminal
but fails in PyCharm (or vice versa). To point PyCharm at it:
File → Settings → Project: <name> → Python Interpreter → Add Interpreter
→ Add Local Interpreter → Existing, then select
.venv\Scripts\python.exe (Windows) or .venv/bin/python
(macOS/Linux) inside your project.
If PyCharm offers to create its own environment when you first open a project, you can accept it and use that as your venv instead — just be consistent about which one you use.
Git¶
Install Git from git-scm.com/downloads (on Windows, accept the default options). Verify it:
git --version
Then tell git who you are — it stamps your name and email onto every commit you make, and refuses to commit at all until you set them:
git config --global user.name "Your Name"
git config --global user.email "your.name@campus.tu-berlin.de"
You only ever do this once per computer. If you skip it, your first commit
in Part 1 fails with *** Please tell me who you are.
Note
git, GitLab, and GitHub are three different things, and it’s
easy to mix them up. Git is the version-control program running on your
own computer. GitLab is a website that hosts repositories — TU Berlin
runs its own at git.tu-berlin.de, and that’s the one this workshop
uses. GitHub is a different, unrelated company’s website that does
much the same thing; the workshop’s templates happen to be hosted there,
which is why you’ll download from GitHub but push your own work to
GitLab.
Your GitLab account¶
All your workshop repositories live on TU Berlin’s GitLab server:
Go to git.tu-berlin.de and sign in with your TU Berlin account (the same credentials you use for other university services).
Your projects belong in the kiwi-git-workshops group. Ask your instructor to add you to it if you can’t see it — being in this group is also what makes continuous integration (Part 2) work.
An SSH key¶
To push code to GitLab without typing a password every time, set up an SSH key once. You generate a key pair: a private key that stays on your machine and a public key you upload to the server, which then recognizes your machine without further passwords.
Generate the key (press Enter at each prompt to accept the defaults):
ssh-keygen -t ed25519 -C "your.name@campus.tu-berlin.de"
Display the public key so you can copy it:
type %USERPROFILE%\.ssh\id_ed25519.pub # Windows
cat ~/.ssh/id_ed25519.pub # macOS/Linux
Copy the entire output — it’s one long line starting with
ssh-ed25519.Warning
Copy the file ending in
.pubonly. The file without.pubis your private key — never share or upload it.In GitLab, click your avatar (top-right) → Preferences → SSH Keys (left sidebar) → Add new key, paste it into the “Key” box, and click Add key.
Verify it works:
ssh -T git@git.tu-berlin.de
You should see
Welcome to GitLab, @yourusername!. The first time, it asks “Are you sure you want to continue connecting?” — typeyes.
An IDE (PyCharm)¶
Install PyCharm — the free Community Edition is enough for everything in this workshop (you don’t need the paid Professional edition, though students can get it free). It has git tooling built into its UI, plus the terminal panel mentioned above.
When you open a project for the first time, PyCharm asks whether you trust it — say yes for your own projects.
You are welcome to use the git command line instead of PyCharm’s git
panels — everything you do in the UI maps directly onto the git commands
explained alongside it — but the walkthroughs assume PyCharm unless stated
otherwise.
Do I need to know Python already?¶
No — the tasks are designed so you can follow them by reading carefully, and each one tells you which file to open and what to change. You’ll pick up the Python you need as you go.
If you’d nonetheless like some ground under your feet before Part 2 (where you start writing code rather than editing it), any short introduction to Python functions, indentation, and imports will do; the official Python tutorial sections 3 and 4, or Real Python’s beginner path, are both good. An hour is plenty — you do not need to finish either before starting.