Version control with Git

3.4. Version control with Git#

Imagine working on a piece of code for a few days or weeks, modifying it over time, only to realize after a while that the code you wrote and deleted on the first day was actually the way to go. Wish you could go back and retrieve that code, right?

In these situations, a habit of working with a version control program comes to your rescue! Git is the most popular software for version control - it allows you to manage the changes you make in your code. Regularly saving your code with Git is extremely useful, as it allows you to track changes, that is, to see all versions that you stored to Git as you were working. In practice, that means that you can trace back everything you deleted and added throughout your work on the code.

../../_images/track-changes.png

Fig. 3.5 Python code with tracked changes (additions in green and deletions in red).#

We recommend you to regularly use Git both while learning with this book as well as in all your future programming. It’s one of the good practices of coding that is nice to make a habit from the get-go.

3.4.1. Git in a nutshell#

You will work only with the basics of Git at this level. These will allow you to save your code and track its version, as well as to retrieve code from a remote repository. Let’s get acquainted with the basic functioning of Git and the appropriate terminology.

../../_images/git-scheme.png

Fig. 3.6 Overview of Git and basic commands. Workspace, staging environment, and local repository are all local, while the GitLab repository is remote.#

Whenever you reach a milestone in your code or finish a part of the work, you should add files to the staging environment (command git add). Staged files are then ready to be committed to the repository (command git commit). You can think of a commit as a “save point” to which you can then go back (as in Fig. 3.5). It’s good practice to add a message to each of your commits - this will allow you (and others, if you’re collaborating on a code) to easily remember what your commit was about. Finally, you can push (command git push) your changes to your remote repository on GitLab, and vice versa, get files from a remote repository with pulling (command git pull). In this context, a repository contains all project files, including the revision history.

Backup

Note that regularly pushing your files not only allows you to go back through the changes of your code, but it also serves as a backup. Should anything happen to your computer, your Python scripts will still be living safely in your GitLab repository.

In its entirety, Git is a rather complex software (e.g., check out this Git glossary to get an idea). Down the line, learning more about Git will allow you to do more complex things than just committing and pushing your changes.

3.4.2. Git in practice (TU Delft-specific)#

GitLab vs. GitHub

This section describes linking VS Code to GitLab, which is specific to the Delft University of Technology and may be applicable to other institutions who host their own GitLab. Besides GitLab, GitHub is another very popular platform for code version control which many individuals use. If you’re not using GitLab, we therefore recommend you to open a GitHub account. Note that some of the instructions below still apply, so it may still be useful to go through them. If you are currently at TU Delft, notice that you’ll lose access to its GitLab after you leave the university - you can then open an account on GitHub and use it for version control and collaboration on your future coding projects.

Your remote repository will be at TU Delft-hosted GitLab, to which you can sign in with your NetID and password.

In order to perform actions of committing and pushing changes to GitLab, you will integrate your GitLab repositories with VS Code. In total, you will have two repositories:

  1. Your private repository, where you will be able to access, work, and store your exercises.

  2. A shared repository with one of your peers, which you will use for peer feedback.

Let’s set up GitLab and link your two repositories to VS Code.

3.4.2.1. Setting up GitLab - SSH key#

An SSH key acts like a digital pass, allowing GitLab to verify that you are authorized to access the repository from your local computer. Without an SSH key, GitLab won’t let you push or pull changes because it can’t verify that you’re a trusted user. Adding an SSH key is a one-time setup step that simplifies your workflow by allowing you to push and pull without repeatedly entering your GitLab username and password.

Therefore, we will first set up the SSH key.

  1. Login to TU Delft GitLab using your NetID and password.

  2. You should be able to see your repositories - a private repository and a repository shared with your peer. A repository/project looks like this:

../../_images/git-project.png

  1. If you click on the name of your project, you will see a page like this:

../../_images/ssh1.png

You will notice the warning regarding the SSH key at the top of the screen.

  1. To check if you already have an SSH key, open your terminal and run ls ~/.ssh. Look for files named id_rsa and id_rsa.pub, or similar. If you don’t see them, you need to generate a new SSH key.

  2. To generate a new SSH key, run ssh-keygen -t rsa -b 4096 -C "your_email@example.com" in your terminal. When prompted, you can press Enter to accept the default file location, and optionally set a passphrase for extra security. Select and copy the entire output, staring with ssh-rsa.

  3. In GitLab, in the upper left corner, find your user profile picture, click on it, and select Preferences.

../../_images/ssh2.png

In the new left sidebar, find SSH Keys and click on it.

  1. Paste your SSH Key into the Key field. Add a title for the key (for example, “My Laptop SSH Key”) and click Add key.

  2. Run this command to test the SSH connection to GitLab: ssh -T git@gitlab.tudelft.nl. You should see a message like “Welcome to GitLab, @username!” which means the connection is working.

3.4.2.2. Git integration in VS Code#

We will clone/download GitLab repositories to your computer from within VS Code. You will first clone your private repository from GitLab. Then you can repeat the process for the shared repository.

The process consists of 2 parts: finding the links (URLs) for your repositories and linking them to your VS Code.

Part 1. GitLab repository link

  1. If you’re not already logged in, login to TU Delft GitLab using your NetID and password.

  2. You should be able to see your repositories - a private repository and a repository shared with your peer.

  3. If you click on your project, you will see a page like this:

../../_images/git-link.png

  1. Click on the blue button “Code” (circled red on the image). In the dropdown menu, press the copy icon next to “Clone with HTTPS” to copy the URL to your repository to your Clipboard. You are now ready to go to VS Code for Part 2.

Part 2. Cloning repository in VS Code

  1. In VS Code, go to View and open the Command Palette. You will find View at the very top of your screen in the menu bar, next to other options such as File, Edit, Selection, etc.

  2. Type Git: Clone and select this command. If your VS Code does not display Git: Clone as an option, close your VS Code, open it again, and try steps 1 and 2 one more time.

  3. In the dialog that appears, paste the GitLab repository URL that you copied to your Clipboard in Part 1. If VS Code starts asking you about linking to GitHub, don’t allow it. We’re not linking to GitHub but rather to GitLab.

  4. You will be asked to select a local folder where the repository should be cloned. For this purpose, open a new empty folder in a location of your choice. Choose something meaningful and easily findable, e.g., a subfolder of your studies in the Documents directory. When you make this selection, cloning will start. It may take several minutes.

  5. During this process, a new window will pop up and ask for your GitLab credentials. You should fill in your NetID and password.

  6. Once the repository is fully cloned, VS Code will ask if you want to open the project. You can decide not to do this right now.

  7. In VS Code’s built-in terminal, navigate to the your GitLab repository’s folder that you selected in step 4 and then run this command:

git remote add origin git@gitlab.tudelft.nl:username/repository-name.git

where you replace username with your username and repository-name with your repository name. This step sets the remote URL to use SSH instead of HTTPS.

Now repeat Part 1 and Part 2 for your shared folder. You can then start working on your Python projects and manage Git directly in VS Code.

SSH vs. HTTPS

Using SSH instead of HTTPS has a few practical advantages:

  • Easier authentication: With SSH, once you’ve set up your SSH key and added it to your GitLab profile, you don’t have to enter your username and password each time you push or pull. SSH keys provide secure, password-less access to your GitLab repositories, which is particularly helpful if you’re frequently pushing or pulling changes (which you are encouraged to do).

  • Enhanced security: SSH keys are generally more secure than password-based authentication. When you use an SSH key, you are authenticated through a key pair (a public and a private key) instead of through a password. This reduces the risk of unauthorized access, especially for sensitive repositories.

  • Avoiding rate limits or two-factor authentication prompts: Some Git platforms, including GitLab, enforce rate limits on HTTPS requests or require re-authentication due to two-factor authentication (2FA) policies. With SSH, once your key is configured, these restrictions won’t interfere with your workflow.

3.4.2.3. Working with Git in VS Code#

3.4.2.3.1. Checking Git status in VS Code#

  1. On the left sidebar, click the Source Control icon (represented by a branch icon).

  2. VS Code will show the current state of the repository:

  • Untracked files: New files added.

  • Modified files: Files that have been changed.

3.4.2.3.2. Making changes, staging, and committing#

  1. Make changes to the Python code in the editor.

  2. In the Source Control tab, hover over the file and click the + icon to stage the changes.

  3. Write a commit message in the input box at the top of the Source Control tab (e.g., “Added function to calculate sum”).

  4. Click the checkmark icon (✔) to commit the changes.

3.4.2.3.3. Pushing changes to GitLab#

  1. After committing, push the changes to GitLab:

  • Click the three dots at the top of the Source Control tab, then choose Push.

  • If prompted, enter the GitLab credentials (username and personal access token, which can be generated from GitLab under Settings → Access Tokens).

  1. The changes will now be uploaded to your repository on GitLab.

3.4.2.3.4. Pulling updates from GitLab#

If someone else (teachers or peers/collaborators) makes changes in your repository, you can pull the latest updates:

  1. Go to the Source Control tab.

  2. Click the three dots at the top and choose Pull to fetch the latest changes.

3.4.2.3.5. Collaboration#

You can collaborate on GitLab by:

  • Committing your changes.

  • Pushing your changes to the shared repository.

  • Pulling the changes made by others from GitLab.

Merging conflicts

With Git, it is possible to collaborate on the same piece of code. In that case, the changes made by different people are merged once they push them to Git.

VS Code handles merging changes automatically, but in case of conflicts (e.g., when two people modify the same file, which in principle shouldn’t happen during peer feedback), Git will flag the conflict, and VS Code will help you resolve it.

Contents