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¶
Go to git.tu-berlin.de and sign in.
Click the + button in the top navigation bar → New project/repository.
Choose Create blank project.
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.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¶
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.Open the outer project folder in PyCharm (File → Open, select the folder, and accept “Trust project”). Point PyCharm at the
.venvyou just created, as described in Prerequisites.Using the full workflow from Part 1: Git Basics (update → branch → commit → push → merge request → merge), edit
README.mdto describe what the package does. The generated file containsTODO(Task2)markers showing where to write.README.mdis 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 ascode. 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.
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
Now actually run one. The project folder contains
sample_picture.jpgto 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 newthumb.jpgappears 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.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.
Open
git_workshop_basic/cli.py— that’s the inner folder — and find thethumbnailfunction. The line that sets the size is:size = (128, 128)
The two numbers are the maximum width and height in pixels.
Change them to something noticeably different (e.g.
(32, 32)).Test that it works: re-run the
image_magic thumbnailcommand 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.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.
Try the rotate command first, so you can see what changes. It needs an
--anglein degrees:image_magic rotate --input-path=sample_picture.jpg --output-path=turned.jpg --angle=90
Document that functionality in
README.md— and commit just this change, on its own.Now find the
rotatefunction incli.py. It calls Pillow’sim.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.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 onlycli.py, write a different message, and commit again. Both commits go onto the same branch and into the same merge request.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.
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
thumbnailcommand incli.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.Document the new feature (as its own commit).
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.