What git does

Git keeps track of changes in a local repository you set up on your computer. Typically that is a directory that contains all your code and optionally the data your code needs in order to run. The local repository contains all your files, but also (in a hidden directory) all the changes to the files you have made. It does not keep track of all files automatically: you need to tell git which files to track and which not. Therefore a repository contains your current tracked files (workspace), an index of files that are being tracked, and the version history.

Every time you make significant changes to the files in your workspace, you have to add the changed files to the index, which selects the files whose changes you want to save, and commit them, which means saving the changes to the history tracking of your local repository.

Often you also setup a remote repository, stored on an online platform like GitHub, GitLab or others. It is simply a remotely-hosted mirror of your local repository and allows you to have your work stored in a safe place and accessible from your other computers and potential collaborators. Once in a while (at the end of the day, or every new commit if you want) you can push your commits, which means sending them to the remote repository so it keeps in sync with your local one. When you want to update your local repository based on the content of a remote repository, you have to pull the commits from the remote repository.

Summary of git semantics

• add: Tell git that you want a file or changes to be tracked. These files/changes are not yet saved in the repository! They are listed as “staged” in the index or staging area for the next commit.
• commit: Save the staged changes to your local repository. This is like putting a milestone or taking a snapshot of your project at that moment. A commit describes what has been changed, why and when. In the future you can always revert all tracked files to the state they were at when you created the commit.
• push: Send previous changes you committed to the local repository to the remote repository.
• pull: Update your local repository (and your workspace) with all new stuff from the remote repository. This command is simple, but potentially destructive, since it overwrites your files with the ones in the remote server. Hence it is not available in the Git GUI.
  • fetch: Get information about the latest commits from the remote repository, but do not apply them to your local repository automatically. This is always safe as it does not change your workspace.
  • merge: Merges two versions (branches) into one, applying the result to the workspace. This includes merging commits from the remote repository with the commits of the local repository. In effect, a fetch followed by a merge is the same as a pull, but it allows you more fine-grained control and is available through the Git GUI.
• clone : Copy the content of a remote repository locally for the first time.
• more advanced:
  • branch : Create a branch (a parallel version of the code in the repository)
  • checkout: load the status of a branch into your workspace

Account setup

The first thing we need to do when starting to work with Git on a new device is to create a secure connection between it and the server we will be using to store our repositories. Git by itself does not handle security, and rather offloads that task to a program called ssh, which means Secure Shell. SSH is the program you would use to connect to a remote computer using the command line, such as when working on a remote server. It requires the use of a pair of randomly generated keys to identify each device to each other.

One key is the private key, it can be used to decrypt messages sent to your computer. The private key does not ever leave your computer and is never sent over the network. The public key is used to encrypt messages, and only the private key can be used to decrypt messages encrypted by your public key.

You can think of the keys a bit like your online bank account. The private key is like the password to log into your online bank (but safer, as it never leaves your computer), whoever has it can use the money in the account. In contrast, the public key is like your bank account number. You can post it on your website and in social media, because the only thing that others can do with it is to send money to it. And if you send money to someone else, they can also use your public account number to verify that the money indeed came from you.

Therefore, the first step is to generate a key pair, and the second step is to register the public key in our Git hosting service (GitLab), so that you link your computer to your account.

1. Launch your key manager

You can create the key pair in three ways. The easiest graphical way to do it is to use the Passwords and Keys app. Click Show Apps at the bottom left and either click on Utilities → Passwords and Keys, or just start typing Passwords and hit Enter.

Utilities in Ubuntu 24.04

2. Create an SSH key pair

Click on the + icon at the top left and select Secure Shell key.

Passwords and Keys

Give a description of your device, e.g. “VirtualBox for Geoscripting”. Click Generate, and the app will ask you for a passphrase. A passphrase is an extra layer of security, where if someone manages to obtain your private key, they will not be able to use it without knowing your passphrase. In other words, it’s encryption for your private key. It’s useful to set a passphrase for keys that are on shared computers, because other users will then not be able to read it even if they manage to access the file. However, if you set a passphrase, you will have to enter it every time that Git communicates with the server. That will get quite annoying very quickly. Therefore, since you are working on your personal virtual machine, just keep the passphrase field empty. If someone does manage to somehow obtain your private key, you can always simply revoke your public key.

Now double-click on the newly generated key, and click the copy button next to Public Key.

Copy the newly generated public key

Note: Passwords and Keys is only available in Linux (GNOME desktop environment). If you want to generate keys on other platforms, use any of the following methods.

The first option is to use Git GUI. Git GUI is a graphical interface to Git that is developed together with Git itself, and is thus cross-platform. Windows users can obtain it by simply downloading git and installing it to obtain Git GUI.

When launched, it looks something like this:

Main screen of Git GUI

You can generate a new SSH key pair in Git GUI by going to Help → Show SSH Key and pressing the Generate Key button. Once done, you will see your new public key:

SSH public key generated

The second option to generate keys is to use the terminal. This is especially useful if you are using a server without a GUI, or using a different Linux distribution or desktop environment. Simply run the command in the terminal: ssh-keygen -t rsa -b 4096

In all cases, by default the public key is stored in the file ~/.ssh/id_rsa.pub (where ~ indicates the user’s home directory). You can read it from the terminal by running: cat ~/.ssh/id_rsa.pub

Next, we will link our client with a Git host so that we can download and upload repositories.

3. Log into GitLab

Go to GitLab and log in (using the WUR Single Sign On button). You also need to set up two-factor authentication by going to your profile page.

4. Enroll the public key to your user account

The SSH key pair is used to identify that you own the device. Now you need to tell GitLab about your new key. To do that, in GitLab click on your avatar in the top left and go to Edit profile → SSH keys. Click Add new key, paste the public key in the box, and press Add key.

This only has to be done once (per device/OS you use GitLab on).

Creating a new repository

5. Create remote repository

Now we are ready to start making new repositories! In GitLab, press the “+” button at the top left, select New project/repository (GitLab uses both terms somewhat interchangeably) and Create blank project. Give it a descriptive name and a short description, choose the visibility of the repository and check Initialize repository with a README.

New repository creation on GitLab

6. Configure repository settings

Explore your new blank repository a bit. In the middle, you have buttons to add new files. Choose to add a LICENSE file, as we have discussed in the previous chapter. See Choose a License for a quick overview of what licenses are available. Make sure to choose a license, otherwise basic copyright applies to your code.

On the tabs to the left, you can find that the repository can have issues and merge requests assigned to them. Issues is what is used to give feedback on code, so try and make a few issues and close them. It is useful to know how to use these, as for personal projects it can be used as a to-do list, and for others’ projects you can use it to report bugs or propose suggestions. You may be surprised how responsive developers can be to newly raised issues!

Example issue on GitLab

Next, check out the repository settings. Under the Members subtab of the Manage tab, you can invite other people to collaborate on your repository. Go ahead and invite your team member to be a collaborator with a maintainer role.

7. Get the URL of your new repository

Now that you have a remote repository, it’s time to create a local repository that links to it! Open the main page of your new repository, click the blue Code button at the top right of the page, and copy the Clone with SSH address of your new repository.

Blank GitLab repository

8. Clone your repository

Let’s first clone the repository using the Git Cola app. Open it from Show Apps at the bottom left. Press Clone… and paste the link you just copied into the box. Press Clone and select the directory you want to put the repository into. A subdirectory with the name of the repository will be created for you. After pressing Open, you will get a question about whether you trust the remote machine. You need to answer this with yes (the full word). This puts the GitLab server into a list of trusted servers, to guard against potential impostor servers.

You will end up in an empty Git Cola window:

Git GUI in an empty directory

From the terminal, the same can be achieved with the git clone command (it will clone in your working directory, by default your user directory ~), for example:

git clone git@git.wur.nl:masil001/geoscripting-git-test.git

The repository will be cloned into a subdirectory with a matching name. This is much faster than using any GUI!

To clone using Git GUI, press Clone Existing Repository. Paste the URL you just copied to the Source Location field, and choose a directory you want to store your code in in the Target Directory field. Note: unlike in Git Cola, the Target Directory must not already exist! Git GUI will create it for you.

You will end up in an empty Git GUI window:

Git GUI in an empty directory

9. Tell Git who you are

Before you start using Git, you should tell it what your name and email address is. You need to do that only once per Git installation. You should go to File → Preferences (in Git GUI it’s Edit → Options…) and fill out the options User Name and Email Address under All Repositories . These will be displayed in GitLab.

You can also do that from the terminal:

git config --global user.name "Your Name"
git config --global user.email you@example.com

Working with Git Cola

10. Make changes

To see Git in action, you need to make some changes in your repository. Try it by creating a new file in the directory where you cloned your new project. You can do that using the Text editor (gedit), or from the terminal using the touch command.

Once you are done, go back to Git Cola. If you closed the window, you can get back to your repository by launching Git Cola and clicking on its path in the list. You will see some changes:

Changes pending in Git Cola

To see a list of files with pending changes from the command line, use git status while in a git repository. To see what exactly changed in each of these files, use git diff. For example:

# Go into our repository we just cloned
cd geoscripting-git-test/
# Get list of changed files
git status

Git GUI works equivalent to Git Cola, only that you need to press the Rescan button every time you want it to reload the list:

Changes pending in Git GUI

At the top left corner, the Status panel, you can see all the files that changed in your workspace. If you click on the name of the file, the Diff panel will show you what changed in that file since the last commit. Unless it is a non-text (data) file, in which case it will just note that something has changed. Note: Git is very efficient with storing changes in text files: these diff files are all it stores internally, it does not copy the whole file on each commit. However, it does not deal efficiently with non-text files, and thus you should limit the amount and size of such files as much as possible.

If you double-click on the name of the file in the Untracked category, the file changes will be staged and appear at the Staged category. These are the file changes you want to save and sent to GitLab. You don’t have to stage all files for each commit, only those you actually want to be tracked by git. You can safely ignore some files such as manual backups, temporary files, and the like and they will remain untracked by git, as long as you never stage them. If you do want to stage everything, you can press the Commit → Stage Modified button. If you staged more than you wanted to, you can double-click on the file in the Staged panel to unstage it.

To stage a change from the command line, use git add and a path to the file to stage To unstage, use git restore --staged and a path to the filename. For example:

# Stage
git add hello.txt
# Unstage
git restore --staged hello.txt

11. Commit changes

Once you staged the files that you want to commit, you need to fill out the commit message. This is a brief description of what changes you made between the last commit and the one you are about to create. The top line (commit summary) is the title of the commit, keep that one short. Subsequent lines (extended description) are the description. You may notice that there is a character counter at the top right which goes yellow if you exceed 65 characters on a line. that is intentional, because your commit message should fit within 65 characters per line for easy reading on the terminal. Use new lines to break longer sentences or paragraphs.

If it is the first time you use Git Cola to make a commit, and you haven’t filled out your user name and email, it might complain about it not knowing who you are. In that case go back to step 9.

Next press the Commit button and your commit will be saved locally. A commit is like a saved state: you are always able to roll back the contents of your tracked files to the state they were in when you committed the changes.

To commit a change from the command line, use git commit. It will start a command line text editor so that you can write a commit message. If you want to stage all tracked and changed files and commit all in one step, use git commit -a. To include a message with your commit without using a text editor, you can use the commit command with the -m flag, for example:

git commit -m "Add a new file hello.txt"

10. Push changes to the server

Select Actions → Push, and confirm the push, to send all your changes to your GitLab repository. You can now refresh the GitLab page to see your changes. Well done!

GitLab repository with content

To push changes from the command line, type git push.

11. Pull changes from the server

One of the major uses of Git is collaboration and the ability to synchronise changes across different devices. Multiple users can do changes in the same Git repository (as long as you change the repository settings in GitLab to allow another user to do that), and you can work on the same code on different devices yourself. In both cases, it is important to keep all local repositories in sync with the remote repository. That is done via Git Cola by using Actions → Pull.

If you like, you can test it by cloning the same repository in another directory, making changes and pushing them to the server, then using pull in the other copy. If all goes well, the changes in the server will be applied to your local repository files.

You can do the same on the command line with git pull.

There may be cases where files go out of sync in incompatible ways, however, like two people editing one file at the same time. In that case you may hit a merge conflict. You will see a message such as:

From git.wur.nl:masil001/geoscripting-git-test
   9179eca..6b7ea60  main       -> origin/main
hint: Diverging branches can't be fast-forwarded, you need to either:
hint: 
hint:   git merge --no-ff
hint: 
hint: or:
hint: 
hint:   git rebase
hint: 
hint: Disable this message with "git config advice.diverging false"
fatal: Not possible to fast-forward, aborting.

It is best to try to avoid them. In case it happens, you need to first try to merge the changes. Go to Actions → Merge and select Tracking branch, origin/main. You will get another error message, such as:

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

Now open the file(s) that are mentioned in the message in a text editor and edit them by hand, keeping the parts of the files you need. The conflicting parts will be in between lines of of >>>>, ==== and <<<< symbols. Once you remove the parts you don’t need (including the separators), you can solve the conflict by committing the changed files. The title of the commit will be made automatically. After committing, it will allow you to push the resolved changes back to GitLab.

Forks and merge requests

Now we know how to work with Git and GitLab for our personal work, and how to collaborate on a project with your team member. But what if you want to contribute code to someone else who has not given you access rights, or what if you want to review the code before it’s accepted to your repository? That’s where forking and merge requests come in handy (respectively)!

A fork is your own personal copy of someone else’s repository. GitLab allows you to fork any public repository. You want to make forks whenever you want to edit code but do not have direct commit rights.

12. Fork a repository

Go to your team member’s repository that they created by following the steps above, and then click the Fork button at the top right. (If you can’t find it, alternatively you can go to some other repository, and fork it.) You will find a new repository under your profile, by default with the same name as the original.

13. Make changes, commit and push

After you have your own fork, it is the same as having your own personal repository with the code from the original (upstream) repository in it. Clone it locally, make some changes, commit them and push them back to GitLab, as per steps 7-10. You should see that your changes take effect in your own downsteam fork, but not in the upstream repository.

14. Make a merge request

If you are ready to ask the upstream developers to incorporate your code into their repository, go to the Code → Merge Requests tab and press the blue New merge request button. Select your main branch of your fork as the source.

This will show you all the changes you have made, and if that is what you want to propose for the upstream developers to incorporate, give the name for your merge request (changeset) and a description as to why the upstream developers would want to incorporate your code. After you confirm clicking Create merge request, the merge request will be visible in the merge requests tab of the upstream repository:

A submitted pull request

Then it’s up to the upstream developers to perform a code review and either accept or reject the pull request in the end.

Other Git Cola functionality

You might run into a situation when you have made changes in tracked files, but do not want to keep some of the changes. You can revert one file by right-clicking on it and selecting Revert Unstaged Edits….

The command line equivalent is git checkout \-\- path/to/file.ext, or if you want to reset all changed files, git reset \-\-hard.

Git Cola not only provides a way to make, push and pull commits, but also to visualise the commit history of your repository in a tree graph. There are two ways to do it. The first is to go to Branch → Visualise Current Branch…. For larger and more complex projects with lots of contributors and merges, it might look like some sort of a subway map:

Git GUI history (gitk)

This visualisation tool is called gitk and is the same (old-fashioned) tools that Git GUI uses as well. There is a slightly more fancy way to visualise history in Git Cola by going to View → DAG…, which also shows the history as a clickable dynamic graph.

The history view also allows you to reset the state of the repository to any previous commit by using the context menu. Note, however, that you can only push if you are on the latest commit. So the easiest way to revert changes is to copy over the files to a temporary directory outside of git, reset back, and move the files back into your repository.

The command line equivalent is git log, though it does not show a graph view. You can also run gitk from the terminal directly. A few more options are available from the command line. git revert <commit> will undo changes from a given commit, where <commit> is the commit ID (you can get commit IDs from git log, they look like a long string of letters and numbers). git checkout <commit> \-\- path/to/file.ext will reset a single file to the state it was at the given commit.

You can also browse the history of a repository from your Git hosting service, and GitHub/GitLab even allow editing files from a web interface.

Below you can see a visual summary of what we have described above.

Git workflow overview

That’s it: now you know how to keep track of all your files, so you will never lose them again, and no longer have to worry about making backups or saving multiple versions. In addition, this is the way that free and open-source code development happens in actuality. Also, the exercises and assignments in the course will be delivered and submitted this way, so make sure you are familiar with the whole process!