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.