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. In Ubuntu, click Show Apps at the bottom left and either click on Utilities → Passwords and Keys, or just start typing Passwords in the type to search searching bar and hit Enter.

Utilities in Ubuntu 24.04

2. Create an SSH key pair

Click on the + icon at the top left of the Passwords and Keys app 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. On Ubuntu 26.04 LTS, you may see a pop-up asking to “Allow inhibiting shortcuts” for the app ssh-askpass. This is a security step to protect your passphrase, so just click Allow.

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

In all cases, by default the public key is stored in the file ~/.ssh/id_.pub (where ~ indicates the user’s home directory and indicates the encryption algorithm used, such as rsa or ed25519). You can read it from the terminal by running: cat ~/.ssh/id_*.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 WUR GitLab and log in (using the WUR Single Sign On button).

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 right, select New project/repository (GitLab uses both terms somewhat interchangeably) and Create blank project. Give it a descriptive name, select your username, 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. On the right, 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 work items and merge requests assigned to them. Work items, under the Plan tab, is what is used to give feedback on code, so try and make a few issues, with the New item button, 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 copy on your own computer! Open the main page of your new repository, click the blue Code button at the top right of the your repository page, and copy the Clone with SSH address of your new repository.

Repository link to clone

8. Clone your repository

Let’s first clone the repository using the Positron app. Open it from Show Apps at the bottom left of Ubuntu. In the center of the Welcome page, click on the icon New from Git….

Positron Welcome page

Alternatively, you can find the option New folder from Git… under i) the File tab or New icon in the top-left, or ii) the Folder icon in the top-right. Select the directory you want to put the repository into under “Create folder as subfolder of”. A subdirectory with the name of the repository will be created for you inside the selected directory. After pressing OK, 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 see your files from GitLab copied locally to your computer in the Explorer pane at the top left of Positron:

Positron GUI cloned repository

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!

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 do that from the terminal:

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

If you don’t do this step, you will get an error in step 12. For example, Positron will tell you Make sure you configure your "user.name" and "user.email" in git.

Working with Git

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), Positron, or from the terminal using the touch and nano commands.

Let’s go back to Positron. If you closed the folder in Positron, you can get back to your repository by clicking on its path in the Recent list. You will see some changes in the Source Control tab on the left side of the screen:

Changes pending in Positron

Files marked with U are newly created Untracked files. Files marked with M are Modified files. If you click on a file here, you will get to see the differences from the previous version of the file, unless it’s a binary file.

Note that Git is very efficient with storing changes in text files: these differences 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. As a rule: Do not commit binary files to git unless absolutely necessary!

To see a list of files with pending changes from the command line, use git status while in a git repository directory. 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

11. Stage changes

In the Source Control tab in the blue vertical ribbon on the left, you can click on the + next to the name of the file in the Untracked category. The file changes will then be staged and appear at the Staged Changes category. These are the file changes you want to save and send 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 + button on the “Changes” header. If you staged more than you wanted to, you can remove the file from the Staged Changes category by clicking the - button.

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

12. Commit changes

Once you staged the files that you want to commit, you need to fill out the commit Message. In Positron it is a textbox above the “Commit” button. 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. 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 Positron 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 big 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"

13. Push changes to the server

Select Sync Changes 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.

14. 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. The Sync Changes button not only pushes your changes to the server, but also fetches changes from the server and pulls new changes from the server to your local copy.

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 Sync Changes 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 the same line at the same time. In that case you may hit a merge conflict. In the terminal 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. Run git merge --no-ff. 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 >>>>, ==== 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.

In Positron, when a merge conflict happens, you can likewise open the affected file and edit it. Positron will highlight the conflicting parts and offer quick actions such as “Accept Current Change”, “Accept Incoming Change”. In many cases that will not be enough and you will need to manually merge the changes into something that makes sense. You can either do that manually like explained above, or use the Merge Editor.

The Merge Editor displays both versions side by side, and also gives the final merged output at the bottom. It also allows you to select one of the two versions using checkboxes in each conflict, or to manually resolve it by editing the output in the result pane. In the end once everything is resolved, press “Complete Merge”. You will need to stage and commit all changes you just made, and possibly sync again to push your changes back to the server.

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.

15. 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.

16. 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 downstream fork, but not in the upstream repository.

17. 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 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 in Positron by right-clicking on it and selecting Discard Changes.

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

Positron 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 the “Graph” category in the Source Control pane. 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)

The graph 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.

Another way to visualise file changes is in the Explorer pane, where your local files are listed. Opening a file will give you a Timeline category, listing all the commits specific to that file.

The command line equivalent is git log, though it does not show a graph view. You can also run gitk from the terminal to get a graphical view. 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 restore <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!