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
:doc:`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:
.. code-block:: none
python --version
.. code-block:: none
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 :doc:`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.
Navigating directories
------------------------
A terminal always has a **current directory** (also called the "working
directory") — the folder your commands act on, unless a command is given a
different path explicitly. This is easy to forget about because you don't
*see* a folder the way you do in a file browser, so a few commands help:
* ``pwd`` (macOS/Linux) or plain ``cd`` with no arguments (Windows) prints
the current directory.
* ``dir`` (Windows) or ``ls`` (macOS/Linux) lists what's inside it.
* ``cd `` ("change directory") moves you into ````. ``cd ..``
moves you *up* one level (to the parent folder). ``cd %USERPROFILE%``
(Windows) or ``cd`` with no path (macOS/Linux) takes you back to your
home folder.
For example, if your projects live in a folder called ``projects`` inside
your home folder, and you just generated a package named
``git_workshop_basic`` into it, you'd move into it like this:
.. code-block:: none
cd %USERPROFILE%\projects\git_workshop_basic # Windows
.. code-block:: none
cd ~/projects/git_workshop_basic # macOS/Linux
Note the slash direction differs: Windows paths use ``\``, macOS/Linux
paths use ``/``. Whenever a later task says "run this inside your project
folder" or similar, this is the step it means — ``cd`` there first, *then*
run the given command.
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:
.. code-block:: none
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)
.. code-block:: none
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:
.. code-block:: none
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
then run the activate command again. See :doc:`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: → 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:
.. code-block:: none
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**:
.. code-block:: none
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):
.. code-block:: none
ssh-keygen -t ed25519 -C "your.name@campus.tu-berlin.de"
#. Display the **public** key so you can copy it:
.. code-block:: none
type %USERPROFILE%\.ssh\id_ed25519.pub # Windows
.. code-block:: none
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.
#. 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:
.. code-block:: none
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):
.. code-block:: none
pip install cookiecutter
Verify it:
.. code-block:: none
cookiecutter --version
If you get ``command not found`` (or ``is not recognized``), or an
``externally-managed-environment`` error, see :doc:`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.