Setup

This document explains how to use PB173 Linux Git repository and how to submit homeworks.

Create a project

Do not fork the original repository in GitLab.

If you do so, it will sometimes make GitLab target the original repository when creating a Merge Request instead of yours. If you miss that and submit this Merge Request anyway, you will expose your homework solution to other students.

You can imagine why that is not a good thing.

If you accidentally did fork the repository, it’s okay. Just remove the fork relationship:
Project’s left panel → General → Advance → Remove fork relationship.
The rest of this manual should still apply, except the step 3 below.

  1. Create an empty project pb173-a2022-linux in GitLab FI.

    Make sure the visibility is set to Private, and unselect the option to create the repository with initial README.

  2. Give access right to your tutor.

    Project’s left panel → Project information → Members

    Here, invite your tutor (xlacko1) with role Reporter.

Create a SSH key and add it to your account in GitLab to make the authentication easier.

Local repository

Clone your repository on the computer you wish to use when working on tutorials or homework assignments. This can be Aisa, your own personal computer, someone else’s personal computer you hacked into, …

  1. Clone the repository.

    In the project dashboard, copy the URL (SSH if you have set up your SSH keys, HTTPS otherwise) and clone it on your computer, for example:

    $ git clone git@gitlab.fi.muni.cz:‹LOGIN›/{origin-name}
$ cd {origin-name}

  1. Set up upstream repository.

    From now on, we will call your repository “origin”, and the official repository belonging to the tutor shall be known as the “upstream”.

    Create a new remote in your repository called upstream to point to the official repository. Use either SSH or HTTPS link:

    HTTPS
    $ git remote add upstream https://gitlab.fi.muni.cz/{tutor}/{upstream-name}
    SSH
    $ git remote add upstream git@gitlab.fi.muni.cz:{tutor}/{upstream-name}.git

  2. Update the main branch.

    This step is needed only when you initialize your project for the first time.
    If you clone the repository on another computer, you can skip this. 
    $ git fetch upstream main
$ git merge --ff upstream/main
$ git push --set-upstream origin main

    If your main branch is called something different than main, use that instead of main in the third command.

    --set-upstream origin may look a bit confusing, but it’s not a typo.

    Git is not a Sith lord, so it does not deal in absolutes. Terms upstream and downstream (≈ origin in our case) are always relative and depend on the perspective. For your local repository, there are two possible upstream remotes: your GitLab project, and the original. You want to push your work to the former, so that is what becomes “upstream” for your local repository.

Updating materials

Initially, branch main contains a single (empty) initial commit. This branch is for you to do as you please, and where you are advised to work on your tutorials. You can create other branches if you wish.

Before every tutorial, new materials will be pushed into the seminar branch of the upstream repository. All you need to do is merge them into your main branch.

Make sure you start in your main branch:

$ git status

Now update the materials:

$ git fetch upstream seminar
$ git merge upstream/seminar
$ git push

When you are finished with the tutorials, you are advised to commit and push what you have done to your origin repository.

Corrections

If an error is found in tests or source materials, the correction will usually appear in the seminar branch, and the above commands will be enough to fix it.

However, if an error is found in a source after you are expected to have modified it, the fix will be released as a separate branch to avoid merge conflicts. You will then be advised, but not required, to merge the fix.

Homework

Each seminar will contain a few homework assignments, or tasks. You can choose any subset of these tasks to work on; even empty.

Since this seminar is quite small, we will not use any additional tools, GitLab will be enough. The solution will therefore be submitted as Merge request (MR from now on).

If you decide to solve more than one task, you have to submit each of them in a separate MR.

  1. Start from a clean repository.

    Use git status to confirm you are in your main branch with no changed files.

  2. Create a branch for your homework.

    The name of the branch must have the homework code including the last letter, for example hw03b. Then push your new branch to GitLab:

    $ git switch --create hw03b
$ git push --set-upstream origin hw03b

    If git switch is not available (usually on older systems), use git checkout -b hw03b instead.

  1. Work on your homework.

    In the homework branch you should only modify files regarding the task. Create commits regularly, especially when you want to switch to a different branch. Don’t forget to use git push and git pull as well if you want to access your work from different computers.

  2. Create a MR and submit your homework for review.

    When finished, make sure you made git push. Then create a MR:
    Project’s left panel → Merge requests → New merge request

    • In Source branch, select the branch with your homework.

    • Make sure that Target branch names your project’s main branch.

    • Click Compare branches and continue.

    In the main MR form, fill in a few details:

    • The Title must begin with Draft: CODE where CODE is the homework code, e.g. hw03b. You can add : and your own title after this.

    • Add xlacko1 to Reviewers field.

    • (Optionally) set Assignee to yourself.

    • (Optionally) check Delete source branch when merge request is accepted option.

    You can set other options (like Description or Labels) as you please.

    Finally, click Create merge request.

  3. Now you wait.

    Do not Merge your homework immediately. This is where the Draft: part in the title comes in handy, as GitLab will prevent you from clicking Merge as long as this prefix remains there.

  4. Review.

    You will likely recieve review for your solution in GitLab as well. In rare cases the review might be delivered by an e-mail or an owl.

    If your solution is good enough and clean, your Merge Request will be approved. Otherwise you are expected to work on the task a bit more. Read the review carefully.

    There is no need to create MR for the resubmit, simply switch back to your homework branch, make changes as necessary, and then commit and push them. GitLab will automatically update the MR.

    Avoid squashing commits or using git push --force for review. While these techniques are useful in production environments, they can make homework reviews and updates quite messy.

  1. Acceptance.

    Once your homework is accepted, you will receive a mark in IS for each accepted task. Whether you merge this branch into your main repository is up to you.

Tips and tricks

  1. Use git status before each commit and push.

    This will help you to avoid messing up branches or creating merge conflicts.

  2. Do not leave uncommited work.

    Always create commits for something you have done or finished, especially if you wish to switch branches.

  3. Stash.

    If you want to switch branch, or do something that requires a clean repository, but you have unfinished work that is not worthy of a commit yet, look at the git stash command (man git stash).

    Short version:

    $ git stash

    Take uncommited changes and store them in a stage area (you can imagine it as a virtual commit) without making changes to your current branch. You will end up with a clean repository.

    $ git stash list

    List stashes, useful when you have more than one.

    $ git stash pop [stash]

    When you want to resume working on the stash, use this command to restore changes on top of your current branch. You may wish to specify the stash if you have more than one.

    You can use git stash before git merge or git pull to temporarily clean out the repository.

  1. Graph.

    While there are some external tools to visualise commits and branches of your repository, Git can do that too:

    $ git log --oneline --decorate --graph --all

    You can create a handy alias for this command, like

    $ git config [--global] alias.graph 'log --oneline --decorate --grah --all'
$ git graph
Do not be afraid to ask for help

If you get stuck with Git or you think you messed up, do not panic. Git is a very powerful versioning system, and while it tries to protect you from trouble, it is not perfect. Things like these do sometimes happen.

Do not hesitate to ask for help in IS MU Discussions or on Discord.