BEETLE Git Tutorial

If first html tag is indented, and this include is called after a list, the html tag is considered a list element, and things go wrong. Leaving a hidden unindented line here

If first html tag is indented, and this include is called after a list, the html tag is considered a list element, and things go wrong. Leaving a hidden unindented line here

BEETLE Git Tutorial

ATTENTION: If you miss background information on Gitlab, Git, Unix/Windows or SSH, check out the references at the bottom of this page.

Each BEETLE team will get access to a private Gitlab sub-group where you have write access and can create your own repositories. You must use it while developing your project. It gives you backup and version control functionalities and facilitates cooperation.

To get access to the repository of your team, precisely follow the instructions available at https://renaud-detry.net/teaching/h01q6c/.

Below, you can find a step by step intro to git. Examples are given for beetle1, adapt the commands for your actual BEETLE group!

Before using git, you should now create an SSH key.

Follow this tutorial: https://gitlab.esat.kuleuven.be/help/user/ssh.md

Create your own repository

Once you have registered your sub-group via https://renaud-detry.net/teaching/h01q6c/ and received confirmation that it had been created, go into your BEETLE sub-group, for example for beetle1: https://gitlab.esat.kuleuven.be/beetle-students/teams/beetle1.

Click New Project. Give it a name, for example: comms and click Create Project.

Clone your new repository on your computer

$ git clone git@gitlab.esat.kuleuven.be:beetle-students/teams/beetle1/comms.git

Making commits

After editing source files, stage the ones you want to include in the next commit:

git add file1.cpp file2.cpp

Naming convention: Avoid spaces and special characters in file names. Some Git hosting platforms (including GitLab) can mishandle them, causing broken links, failed CI jobs, or merge issues. Prefer snake_case or kebab-case.

Before committing, review what’s staged:

Command Purpose
git status List files staged for the next commit, and files with unstaged changes
git diff --cached Show the exact changes that will be committed
git diff Show changes that are not yet staged

Once the staged changes form a coherent, self-contained unit of work, commit them:

git commit

Write a clear commit message: a short summary line (≈50 characters), optionally followed by a blank line and a more detailed explanation of why the change was made.

Good practice: Keep commits small and focused on a single logical change. This makes history easier to read, review, and — if necessary — revert.

Pushing changes to the remote

Commits made locally aren’t visible to anyone else until you push them:

git push

This uploads your local commits on the current branch to the corresponding branch on the remote.

Creating a feature branch

Never commit directly to master. All work happens on a dedicated branch, which keeps master stable and makes review possible.

1. Sync your local master with the remote first, so your new branch starts from the latest code:

git checkout master
git pull

2. Create and switch to your new branch (here, myfeature):

git checkout -b myfeature

To switch between existing branches at any time:

git checkout branchname

Publishing a branch

Each contributor works on their own branch, so pushing your work doesn’t risk conflicting with anyone else’s.

The first time you push a new branch, tell Git to link it to a remote branch of the same name:

git push --set-upstream origin myfeature

After that initial push, a plain push is enough:

git push

Merging into master

Before merging your branch, make sure it includes all the latest changes from master:

git fetch
git merge origin/master
git push

This brings master’s latest commits into your branch first. Resolve any conflicts locally (see below), verify tests still pass, and push. Only then open your merge request — this way, the merge on the server side is guaranteed to be clean.

Resolving conflicts

Conflicts can arise during a merge. When they do, Git pauses the operation and marks the affected files.

  1. Identify the conflicting files:

    git status

  2. Open each file and resolve the conflict. Git marks conflicting sections like this:

    <<<<<<< HEAD
your version of the code
=======
their version of the code
>>>>>>> branch-name

    Edit the file to keep the correct content, then remove the <<<<<<<, =======, and >>>>>>> markers.

  3. Stage the resolved files:

    git add <file>

  4. Continue the operation once every conflict is resolved:

    git merge --continue

  5. If you’d rather back out entirely instead of resolving conflicts, abort the operation and return to the state before it started:

    git merge --abort

Quick reference

Situation Command
Stage files git add <files>
Commit staged changes git commit
Push commits git push
Create a branch git checkout -b <name>
Publish a new branch git push --set-upstream origin <name>
Pull in latest master git fetch && git merge origin/master

References

Tools

If git is not provided by your OS, you can download it from the official git website (Windows, Mac OS X, Unix/Linux).