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.

  1. Generate the key (press Enter at each prompt to accept the defaults):

    ssh-keygen -t ed25519 -C "your.name@campus.tu-berlin.de"
    
  2. 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 .pub only. The file without .pub is your private key — never share or upload it.

  3. 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.

  4. 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?” — type yes.

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.

cookiecutter

Parts 1–3 each start from a small starter package generated by a tool called cookiecutter. Install it once (into your base Python, not a per-project virtual environment, since you’ll use it to create new projects, before those projects even have a venv of their own):

pip install cookiecutter

Verify it:

cookiecutter --version

If you get command not found (or is not recognized), or an externally-managed-environment error, see Troubleshooting — both are common and both have a one-line fix.

Each part’s tasks tell you exactly which template URL to run it against.

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.