Part 1 Tasks

These tasks give you a real repository to practice the workflow from Part 1: Git Basics on. Work through them in order — each one builds on the previous task’s result, and each one should be done as its own full cycle of the recipe above (update, branch, commit, push, merge request, merge).

Note

Make sure you’ve worked through Prerequisites first — in particular that python --version, git --version and cookiecutter --version all work, that you’ve set your git identity, and that your SSH key is uploaded to GitLab. If any command below fails with an error, check Troubleshooting.

Task 1: Create a repo

Create the empty project on GitLab

  1. Go to git.tu-berlin.de and sign in.

  2. Click the + button in the top navigation bar → New project/repository.

  3. Choose Create blank project.

  4. Fill in:

    • Project name: something like git-workshop-basics (this also fills in the URL automatically).

    • Project URL: pick the kiwi-git-workshops group if you have access to it, otherwise your own username.

    • Visibility: Private is fine for now.

    Warning

    Untick “Initialize repository with a README”. GitLab ticks this by default, which creates a first commit on the server. If you leave it on, the push in the next section fails with ! [rejected] main -> main (fetch first), because your local history and the server’s history have nothing in common. You want a completely empty project here.

  5. Click Create project. You’ll land on a page showing setup instructions — keep this tab open, you need the repository address from it shortly.

Generate your practice package

Cookiecutter creates the new project folder inside whatever directory your terminal is currently in, so move somewhere sensible first:

cd %USERPROFILE%\projects        # Windows (create the folder first if needed)
cd ~/projects                    # macOS/Linux

Then run:

cookiecutter https://github.com/spirousschuh/cookiecutter-git-workshop-basics

It asks you a series of questions, showing the default answer in square brackets — press Enter to accept a default, or type your own:

author_name [Josephine Doe]: Your Name
author_email [your@address.eu]: your.name@campus.tu-berlin.de
package_name [git_workshop_basic]:
package_description [A lightweight python package to practise some git]:
package_url [https://git.tu-berlin.de/you/your_repo_name]: <paste your project's URL>

The answer to package_name becomes the name of the folder your package is generated into. Use lowercase letters and underscores, no spaces or hyphens — it has to be a valid Python name.

Note

If you run cookiecutter a second time it asks “You’ve downloaded … before. Is it okay to delete and re-download it? [y/n]” — answer y. It’s just re-fetching the template.

How do you know it worked? You now have a folder structure like this (assuming you kept the default name):

git_workshop_basic/            <- the project folder ("outer")
   git_workshop_basic/         <- the Python package itself ("inner")
      __init__.py
      cli.py
   tests/
      test_cli.py
   pyproject.toml
   tox.ini
   README.md
   LICENSE
   .gitignore
   sample_picture.jpg

Important

Note the two folders with the same name. The outer one is your project — that’s the one you open in PyCharm, run git commands in, and run pip install -e . in. The inner one is the Python package containing the actual code. Whenever these tasks say “your project folder”, they mean the outer one.

Connect it to GitLab

Move into the outer project folder and turn it into a git repository:

cd git_workshop_basic
git init
git add .
git commit -m "Initial commit from template"

Now connect it to the empty GitLab project you created and push. Copy the SSH address from your GitLab project page (the Clone button → Clone with SSH); it looks like git@git.tu-berlin.de:kiwi-git-workshops/git-workshop-basics.git:

git remote add origin git@git.tu-berlin.de:kiwi-git-workshops/your-project.git
git branch -M main
git push -u origin main

You should see output ending in something like:

To git.tu-berlin.de:kiwi-git-workshops/your-project.git
 * [new branch]      main -> main

If you instead get Permission denied (publickey) or a rejected push, see Troubleshooting — both are covered there.

How do you know it worked? Refresh your project’s page in the browser. You should now see the package’s files and a rendered README.md.

Task 2: Improve the README

  1. Create and activate a virtual environment inside your project folder (see Prerequisites for the full explanation), then install your package into it in editable mode, so changes you make take effect immediately without reinstalling:

    python -m venv .venv
    .venv\Scripts\Activate.ps1
    pip install -e .
    
    python3 -m venv .venv             # macOS/Linux
    source .venv/bin/activate
    pip install -e .
    

    How do you know it worked? The last lines of the output say Successfully installed git_workshop_basic-0.0.1, and your prompt shows the (.venv) prefix.

  2. Open the outer project folder in PyCharm (File → Open, select the folder, and accept “Trust project”). Point PyCharm at the .venv you just created, as described in Prerequisites.

  3. Using the full workflow from Part 1: Git Basics (update → branch → commit → push → merge request → merge), edit README.md to describe what the package does. The generated file contains TODO(Task2) markers showing where to write.

    README.md is written in Markdown, a simple formatting syntax: # at the start of a line makes a heading, ## a sub-heading, - starts a bullet point, and text between backticks renders as code. GitLab renders it automatically on your project page.

How do you know it worked? After merging, your project’s landing page on GitLab shows your new text.

Task 3: Document the thumbnail command

Your generated package ships with a small command line program called image_magic. It exists because pyproject.toml declares it as an entry point, and pip install -e . wired it up — which also means it only works while your virtual environment is active.

  1. Explore it, running these from your project folder:

    image_magic --help
    

    which prints the available sub-commands:

    Usage: image_magic [OPTIONS] COMMAND [ARGS]...
    
    Options:
      --help  Show this message and exit.
    
    Commands:
      rotate
      thumbnail  Creates a small thumbnail image
    
  2. Now actually run one. The project folder contains sample_picture.jpg to practice on:

    image_magic thumbnail --input-path=sample_picture.jpg --output-path=thumb.jpg
    

    On success it prints Successfully saved image at thumb.jpg, and a new thumb.jpg appears in your project folder — open it (double-click it in PyCharm’s file tree) and you’ll see a much smaller version of the original.

    Note

    Both paths are relative to your current directory, so this only works if you’re in the project folder. The output filename must end in .jpg, since that’s the format it saves as.

  3. Using the full workflow again, document how to create a thumbnail from the command line in README.md.

Task 4: Change the thumbnail size

Your first real code change. From here on, always use the full workflow for every change, however small.

  1. Open git_workshop_basic/cli.py — that’s the inner folder — and find the thumbnail function. The line that sets the size is:

    size = (128, 128)
    

    The two numbers are the maximum width and height in pixels.

  2. Change them to something noticeably different (e.g. (32, 32)).

  3. Test that it works: re-run the image_magic thumbnail command from Task 3 and open the resulting image — it should now be visibly smaller. You do not need to reinstall; that’s what editable mode buys you.

  4. Merge your feature branch.

Task 5: Change the rotation direction, and commit hygiene

This task introduces an important habit: keeping documentation changes and code changes in separate commits, even within the same branch/merge request. It makes the history much easier to read later (“this commit changed behavior, that one just documented it”) and makes it possible to revert one without the other.

  1. Try the rotate command first, so you can see what changes. It needs an --angle in degrees:

    image_magic rotate --input-path=sample_picture.jpg --output-path=turned.jpg --angle=90
    
  2. Document that functionality in README.md — and commit just this change, on its own.

  3. Now find the rotate function in cli.py. It calls Pillow’s im.rotate(angle), which by convention turns the image counter-clockwise. Make it turn clockwise instead — rotating by the negative of the given angle achieves this.

  4. Commit that code change as a second, separate commit.

    To keep commits separate in PyCharm, use the Commit tool window (left sidebar). It lists your changed files with a checkbox each: tick only README.md, write a message, commit — then tick only cli.py, write a different message, and commit again. Both commits go onto the same branch and into the same merge request.

  5. Merge your feature branch.

Task 6 (optional, harder): Color to black-and-white

More open-ended — you’ll need to look things up, which is itself a skill worth practicing.

  1. Add a new CLI sub-command so that this works:

    image_magic color-to-bw --input-path=sample_picture.jpg --output-path=bw.jpg
    

    Copy the structure of the existing thumbnail command in cli.py (the @cli_group.command() and @click.option(...) lines above the function are what turn a plain Python function into a sub-command). For the conversion itself, look at Pillow’s Image.convert — mode "L" means greyscale.

  2. Document the new feature (as its own commit).

  3. Merge your feature branch.

Wrapping up

After merging on the server, your local main is now behind the remote — the merge happened on GitLab, not on your machine. Switch back to main and pull, which is exactly step 1 of the cycle:

git checkout main
git pull

You can also delete a merged branch (GitLab offers a button for this in the merge request, and PyCharm can delete the local copy) — once merged, it has served its purpose.

Once you’re comfortable with this cycle, move on to Part 2: Testing.