Git Workshop

Overview

The workshop starts at the section Workshop in this document.

If you haven’t yet configured your local computer to be able to use the EPFL GitLab using your own ssh key, follow the Setup Access to GitLab section. If you have already done that, skip to the Workshop section.

Setup Access to GitLab

Local configuration

You need to have git installed. - MacOS: Install brew, git is packaged with it - Windows: Install git bash (or use WSL, if you know how to) - Linux: Install git via your package manager, you know how ;)

In order for you to access a Git remote (like the EPFL GitLab), GitLab needs to validate that it is in fact you that is connecting to your repository.

The authentication is done via public key cryptography, which means we have to generate a private key (that only we know) and a public key (which we can give to GitLab).

Make sure no ed25519 key exists already (output should be empty)

ls -la ~/.ssh/id_ed25519*

• If a key already exists, skip the key generation to ensure that the key will not be overwritten.

Generate a new key with the following command and follow the prompt (keep the name as ~/.ssh/id_ed25519 as suggested by the prompt):

ssh-keygen -t ed25519

In this example, we select the more modern ed25519 key instead of RSA. But an RSA key is totally fine too. Optional: Click here if you want to learn why.

Let’s view the public key that we will later use for GitLab:

cat ~/.ssh/id_ed25519.pub

Now, set your email and username for GitLab. Replace the variables written with caps lock with your real email and name and enter the command:

git config --global user.name "FIRSTNAME LASTNAME"
git config --global user.email "FIRSTNAME.LASTNAME@epfl.ch"

Configuration on GitLab

We have now created a key locally, but the GitLab doesn’t yet know that.

The public key we generated has to be added to GitLab.

1. Sign in to the official EPFL GitLab: gitlab.epfl.ch

2. Go to: Your profile icon (on the left) -> Preferences -> SSH Keys (left) -> Add new key (top right)

3. Paste your public key and add it to GitLab.

Example: Adding a new ssh key to GitLab

Workshop

This workshop aims to simulate working on a project with team members using git.

Our goal: just_do_git.py is a program that just prints I love git!. However, as a simple feature, we want it to display I <3 git!

Your team members will be bots that simulate working on the project, by doing merge requests, merging your changes, etc…

Note: If you follow this instruction, everything you add to the just do git - lab repository will be publicly visible. If you want to delete your branch and thus your changes at the end of the workshop, follow the cleanup section at the end of this page.

Access to Repository

1. Go to the lab repository: gitlab.epfl.ch/gnugen/just-do-git-lab

2. Request access on GitLab. Click on the 3 dots on the top right and click request access.

Example: Requesting access.

A bot will grant you access automatically ~30 seconds after clicking request access

3. Clone the repository

   git clone git@gitlab.epfl.ch:gnugen/just-do-git-lab.git

Git Workflow

The workflow in our repository is structured in the following way:

You are the team leader and thus maintain develop/USERNAME branch, this is non-production code which your team merges features and fixes into.

• Normally there is only one develop branch, but as all workshop attendants should work on a develop branch, we selected the name develop/USERNAME to avoid conflicts.

At the same time, you also create a new feature in a feature branch named feature/FEATURE_NAME/USERNAME, that you want to merge into your develop branch.

• Normally this branch is only named feature/FEATURE_NAME.

Along the way there will be some complications, your digital team members (our bot) will make your life a bit difficult ;)

To summarize (you will replace the variables in caps later with your own username / feature):

• main: stable branch that contains production-ready code. Managed by gnugen
• develop/USERNAME: integration branch where new features and fixes are merged before being released. Managed by you and our bot
• feature/FEATURE_NAME/USERNAME: temporary branch created from develop to build and test a specific new feature or change. Managed by you

Our setup is heavily inspired by the GitFlow workflow

The Develop Branch

1. Create your own develop branch locally (replace USERNAME with your gaspar / EPFL username)

   git checkout -b develop/USERNAME

   Please name your branch as indicated in the command above with your gaspar / EPFL username (usually your last name), for the bot to work correctly

2. Push your branch to the remote, check if it is visible in the GitLab UI

   • Need a hint? - Click here to reveal a hint

     Try the following command and use the commands it proposes:

     git push

Is your branch visible in GitLab? If yes, congratulations! Advance to the next step.

Development branch visible in GitLab

The Feature Branch

We create a new feature to replace the output of or just_do_git.py application

1. Create your own feature branch locally (replace USERNAME with your gaspar / EPFL username):

   git checkout -b feature/replace_love_with_heart/USERNAME

   Please name your branch as indicated in the command above with your gaspar / PFL username (usually your last name), for the bot to work correctly

2. Push the branch to the remote (analogous to the develop branch)

3. We add our feature in the code

   • Edit just_do_git.py
   • Replace love with <3
   • Change nothing else

4. Display your changes in the command line

   git diff

5. Now, stage, commit and push your changes

   • Need a hint? - Click here to reveal a hint

     Try the following command and use the commands it proposes:

     git status

Reload GitLab, do you see your changes? If yes, everything went well, advance to the next step.

The commit is visible with the comment just_do_git.py: output: change 'love' to '<3'

Merging

As you added your feature to the feature branch, is now time to merge your changes into develop.

We can either create a merge request on GitLab or use the command line to merge the branches. As the command line is way more fun, we will do it that way.

1. Go to the develop branch and pull potential changes from your team (the bot).

   git checkout develop/USERNAME
   git pull

   Updating 1cc78fc..c11576d
   Fast-forward
    just_do_git.py => i_love_git.py | 0
    1 file changed, 0 insertions(+), 0 deletions(-)
    rename just_do_git.py => i_love_git.py (100%)

   • We see that a change occurred: just_do_git.py was renamed to i_love_git.py.

2. Merge feature/replace_love_with_heart/USERNAME into develop/USERNAME with merge and rebase. This will be a bit tricky as the file we made the changes to no longer exists.

   Hint: No merge conflict has to be resolved, and no other commits have to be made if done correctly.

   • Need another hint? - Click here to reveal a hint

     Before the merge, switch back to the feature branch and update it to the current state of develop using rebase. You have to force-push your changes here. Do you know why?

     git checkout feature/replace_love_with_heart/USERNAME
     git rebase develop/USERNAME
     git push -f

Check the history of the develop branch in GitLab, you should have the commits of your feature branch, as well as the bots feature branch. If this is the case, advance to the next step.

All commits are visible

Another Merge Request

Just as you solved your previous problem with a rebase, somebody else decides to edit the exact same line you did and create a merge request.

In this scenario (because of our bot setup), you don’t have write access to the feature branch that will be merged. Assume the maintainer of the branch is on vacation and forgot to unprotect their branch (give you access to it).

You were assigned said merge request on GitLab:

The merge request on the GitLab interface.

Let’s solve the problem locally for some git practice!

1. Checkout to the develop branch
2. Merge the branch feature/replace_love_with_heart/gnugen-bot using the git merge command.

   1. An error message will appear:

      Auto-merging i_love_git.py
      CONFLICT (content): Merge conflict in i_love_git.py
      Automatic merge failed; fix conflicts and then commit the result.
      

   2. Edit i_love_git.py to solve the conflict.

      • Need a hint? - Click here to reveal a hint

        Remove the headers and footers git added and delete the line you don’t want to keep.

        In the end, the file should normal, as you want to keep it without <<<<<<< HEAD:i_love_git.py, =======, etc…

   3. Once you edited i_love_git.py, you need to complete your merge. Stage your file, commit your changes and finally push to the remote.

      • Need a hint? - Click here to reveal a hint

        Type the following command, which will give you suggestions on what to do:

        git status

Check the state of your merge request in GitLab, it should not have any conflict anymore! But as you already merged it manually, you can close the request

The merge request on the GitLab interface.

If you made it this far: congrats!

This is the end of the (git-)lab ;)

You successfully collaborated with your team to create a new version of just_do_git.py and solved 2 merge conundrums!

Now, you can create your own repositories and experiment with git on your own. Or create a repository for your actual projects at EPFL.

If you want to instead to improve your git skills using a game, we suggest Oh My Git! - open ohmygit.org - click on the button labelled “Download the game!” below “Play the game!” - and follow the instructions for your OS

Survey

We value your feedback!

To make the workshop even better next year, feel free to fill out this survey so we know if you liked the workshop and how we can improve it.

It only takes 2 minutes and helps us a lot! :))

Cleanup

Do you want to delete your branch as you don’t want your edits as part of this workshop to be publicly visible?

This will delete your branch and its code / data irreversibly on GitLab! In your own projects, it’s not smart to delete branches (unless they are temporary branches, such as feature branches), as your code and its’ history will be gone.

Make sure to only delete your own branch, and not the branch of somebody else!

List your local branches:

git branch

Delete the branch on the remote. Replace USERNAME with your username (branch name you used before)

git push -d origin feature/replace_love_with_heart/USERNAME
git push -d origin develop/USERNAME