Git Beginners¶

Welcome to GitLab!¶

If you are looking for GitLab's docs, they are here.

Git quick reference¶

This is a quick reminder of the basic commands.

Simple Git Flow¶

1. git pull to bring changes from GitLab to the local repository.
2. Make changes to your local files in the repository.
3. git add files to the index (staging area).
4. git commit to move changes from the index to a local commit.
5. git push to send local changes to GitLab.

Git Setup¶

Simple Git Commands¶

First time using GitLab¶

This section is aimed towards first time users of both Git and this instance of GitLab.

What is Git and GitLab?¶

Let's get this info from git's website:

Then from the Wikipedia page about GitLab:

For you, as a student, this means you will:

1. Have at least have one backup of your code in a safe place, provided you push your local changes back to the CS GitLab server,
2. Have version history of all your changes, provided you've pushed each change to the server,
3. Learn how to use version control to help prepare you for the working world,
4. Be able to safely submit and track your code, with the over-site of the lecturers and demis.

Login¶

GitLab has been set up such that you can log in with your Stellenbosch University credentials.

1. Navigate to https://git.cs.sun.ac.za/users/sign_in, or click here to open the login page in a new tab.

2. Now click the US Office365 button encircled in red in the below image.

   

3. You will be re-directed to the Microsoft office OAuth system to log in with your Univerisy credentials.

Congratulations! You should now be logged in. You won't be able to create any projects or groups as an undergraduate, but if you are a postgraduate, you can request permissions for this.

If you have been enrolled in a course that uses GitLab for projects, you should see the projects listed on this page.

SSH key Setup¶

Next, we will need to add your SSH key so that you can clone a copy of the project repository (or repo for short) to your local PC. We assume you are using a NARGA machine in Ubuntu, but these instructions should be applicable for any Linux machine.

The purpose of the SSH key is for you to authenticate that you are who you say you are to the server. So DO NOT share the key, or your password that you used to lock the key. Keep your password safe, but don't forget it! You should note it down somewhere safe and keep it with you as you will need it to unlock the SSH key in future.

Generate a new SSH key¶

Courtesy of Willem Bester.

1. Log into your lab account, and open a terminal.

2. On the command prompt, type the following, and hit Enter.

   ssh-keygen -t rsa -b 4096
   

3. Just hit Enter to accept the default when the program responds with

   Generating public/private rsa key pair
   Enter file in which to save the key (/home/user/.ssh/id_rsa):
   If you had an existing key pair, the program will display:
   /home/user/.ssh/id_rsa already exists.
   Overwrite (y/n)?
   Type y and hit Enter to overwrite.
   

4. The program will now prompt you to enter and confirm your passphrase. In each case, enter your passphrase, and hit Enter. Do not leave your passphrase empty!

   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   If you entered the same acceptable passphrase correctly twice, the program will display something like:
   Your identification has been saved in /home/user/.ssh/id_rsa.
   Your public key has been saved in /home/user/.ssh/id_rsa.pub.
   The key fingerprint is:
   7b:04:31:39:cf:18:5a:b9:74:e3:53:cc:2d:32:72:b1 user@host.com
   The key's randomart image is:
   +--[ RSA 4096 ]----+
   |        oo.+ .    |
   |        Oo*.= .   |
   |       +.%E= .    |
   |      . o.=       |
   |        S ..      |
   |         o        |
   |        . .       |
   |         .        |
   |                  |
   +------------------+
   

Add SSH key to GitLab¶

Now we will copy the key you have just created to your GitLab account.

1. Open terminal.

2. Type: cat ~/.ssh/id_rsa.pub.

   For example (usually the key appears on more than one line):

   cat ~/.ssh/id_rsa.pub
   ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB/Qw/T0HlOcbh+joCpYjyQQo4X0C0JHDhw08EPxjYs1vC1eiN3Rd6rL7YGhQqhmhduoAwMZszqN8HL/lXVecljbGzh5e6nPt47yrCMO8LRW5tjUc1yF9SVpslqI+ehFX6aFFMByMLCA5Z4LHiukTQ0fdgfhfggfhdgfnQYuzD8e2nywBCWUeGK+nNmqVbgcZoH6xPHeiLV+g+1mBLOmZzNzHLCzteHXRISzb/3AthRq6YVPFCHRLfubekQCCXlYHYCjA890dQ-s+9SUjBpYXB/VvYKYolW1diXSQ7VvkD38BJlOq6L9pKH0NlAxhAEzUSfrWN0gm8OBkIBb/dksIDxQvUUmvEiD4DW693RUevl/1hZsZ/hQmk3TSdK62C7z7eSlroS59eCcaAVRL009crF3H3gAUjMh/XfBY9nw+8HBpBA6BlOSI29owviZFUexVHcUG6SVkGyaH/Z9R6cYJZnDIRC4MmDNDVUnERR+1dAhgXHIqpYDG0h5cWlDvpzosIAkPK5y+/ExsjCPkRlEX5mMgL7Nm5pmtD/avxCeQRVRRsag//FPY50Nns8a4+J5yZb0uM8eTEAug1CDSNrmSl4ofrchCJxvVo9BQ0yA/kS9I2ffnUhftr/TzhlXQVkGx3/7+aSA6vpXgWByrPiW4fDilPq0Gp8XZJP8DIwiPGt1GXp name@example.local
   

3. Now, in your terminal, copy everything from (and including) the ssh-rsa to the end of what would be the example.local from the above. You should have copied the entire output from the command.

4. In GitLab, click the top right button by your name (you'll need to be logged in) and choose Preferences then SSH Keys from the left menu. It will look like this:

   

5. Paste the key you copied into the Key section, and add a name for your key, or leave the default.

6. Click "Add Key". This option will only show up if the key is correctly copied over.

You have successfully added your key to the server. You can now get your code from the server, and send your changes back to the server.

First "clone", "change", "commit" and "push"¶

In this section we will learn how to clone your project down, add changes to it, commit those changes and send them back to the server.

Before we begin¶

Before we clone down a project for the first time, there are a few things we should set that will allow us to avoid future questions.

First, set up your username and email address globally with the git config commands. This will allow you to identify yourself in a friendly way to the server. You can find the commands here and here respectively.

Next, let's set git to only push your current branch when using the git push command. This is the recommended default behavior. Use this command to achieve this behavior.

First project clone¶

Let's get your code from the server to your local machine.

1. In the browser navigate to Projects (top left) and click Your Projects. Then select the project you would like to clone to your local PC.

2. Copy the git URL by clicking the copy button. See the section encircled in red below. Ensure that SSH is selected on the left of the URL box.

   

3. Open a terminal and use "cd" to change directory to where you would like to store your code. For example, below I create a new directory in my home directory called "git", I then "cd" into that directory.

   # "~/" is a shortcut for your home directory
   $ mkdir ~/git
   $ cd ~/git
   

4. Let's finally make a local copy of your code! In a terminal type and paste git clone <copied URL>.

   Tip

   To paste in terminal, use the keys ctrl + shift + v.

   Note

   Since this is probably the first time you have connected to git.cs.sun.ac.za, you will be asked if you want to trust this host. We are vouching for git.cs.sun.ac.za, so you can safely type yes.

5. For example, this is what happens if all goes well:

   $ git clone git@git.cs.sun.ac.za:slug/netbot.git
   Cloning into 'netbot'...
   remote: Counting objects: 430, done.
   remote: Compressing objects: 100% (57/57), done.
   remote: Total 430 (delta 52), reused 80 (delta 41)
   Receiving objects: 100% (430/430), 68.86 KiB | 530.00 KiB/s, done.
   Resolving deltas: 100% (215/215), done.
   

If you have successfully cloned your code onto your local PC, well done! You should see a new directory within the directory you created with the same name as your project name.

Otherwise, if something went wrong, make a note of the error you encountered and ask a demi for help.

Make a local change¶

Let's create a file in your git directory and see how this change is shown in git.

1. First "cd" into your newly cloned repository. For example following from above:

   $ cd ~/git/netbot/
   

2. Now create a new empty file using the "touch" command.

   # First we "ls" to list what is in the directory
   $ ls
   
   # We see there is nothing. So let's create a file called "fred.txt"
   $ touch fred.txt
   
   # Now if we "ls" again we see that fred.txt exists
   $ ls
   fred.txt
   

3. Now let's ask git what has changed in the repository with "git status":

   $ git status
   On branch master
   Your branch is up to date with 'origin/master'.
   
   Untracked files:
     (use "git add <file>..." to include in what will be committed)
   
       fred.txt
   
   nothing added to commit but untracked files present (use "git add" to track)    
   

   We see that there is a file called "fred.txt" that is not yet in the index, or in the repository.
4. Let's do as suggested and add the file with git add fred.txt.

5. If we type git status again we see:

   On branch master
   Your branch is up to date with 'origin/master'.
   
   Changes to be committed:
     (use "git reset HEAD <file>..." to unstage)
   
       new file:   fred.txt
   

   Now we see that there are local changes that have not been committed, but are being tracked.

   Do step 2 to 4 again with a new file called "java.txt".

   Now when we git status we see:

   On branch master
   Your branch is up to date with 'origin/master'.
   
   Changes to be committed:
     (use "git reset HEAD <file>..." to unstage)
   
       new file:   fred
       new file:   java.txt
   

6. Once you have made all the changes you want for a certain piece of work, you can commit them all together after adding them.

   We commit these changes with the command git commit. Once you issue this command, you will be prompted with a text editor of your choice so that you can add a comment to this set of changes.

   This is as if you are saying "this is a group of changes that belong together and that I am finished with for now".

   In this message you will also see a summary of changes. You should see both "fred.txt" and "java.txt".

   Once you have saved your message, you should see something like this:

   [master 6b46d28] Added Fred and Java to fix bug 33
    2 files changed, 0 insertions(+), 0 deletions(-)
    create mode 100644 fred.txt
    create mode 100644 java.txt
   

   This means your changes have been successfully committed! However, they are not on the server yet.

Sending code back into GitLab¶

Now that we have added a commit, we need to send those changes back into GitLab.

1. Back in your terminal, "cd" into your project directory.

2. Type git push origin master.

   Tip

   In future you only need to type git push. We only use origin master here because this is the first time we are pushing to this empty project.

3. You should be prompted for your SSH key password. Enter this and hit "Enter". If all goes well, you should see something like the below.

   Counting objects: 3, done.
   Delta compression using up to 4 threads.
   Compressing objects: 100% (2/2), done.
   Writing objects: 100% (3/3), 437 bytes | 437.00 KiB/s, done.
   Total 3 (delta 0), reused 1 (delta 0)
   To git.cs.sun.ac.za:slug/netbot.git
      715fe21..6b6d123  master -> master
   

   Congratulations! You have added your local changes to the server. Feel free to click around in the browser to see what this looks like.

Best practices for your own (and others) sanity¶

1. Add changes to your commit often.
2. Commit and push when-ever you step away from your work.
3. Try keep all changes that are in a commit related. Remember you can create many commits by adding only specific files to a commit, then push all the commits to the GitLab server at once.
4. Make your commit messages helpful. Short, but descriptive. Remember you can enter a 2^nd line of text.

Conclusion¶

You should now be able to manage and contribute to your project! Good luck, and if you spot anything wrong with the wiki, or have suggestions, please log an issue about it here.

Troubleshooting¶

SSH Agent refuses to sign and send key¶

When trying to clone/pull/push, if you find yourself getting this message:

sign_and_send_pubkey: signing failed: agent refused operation

Issue SSH_AUTH_SOCK=0 in your terminal and try again.

If your opperation succeeds, then Gnome Keyring is to blame.

To fix this long term disable the ssh-key agent from the gnome startup settings. The SSH Key Agent setting should be unchecked like below.

Now logout and log back in to test if things are working.

SSH connection check¶

If you are struggling to connect to the server, try run ssh git@git.cs.sun.ac.za from the PC you want to connect from. For example, a correctly working key should produce the below output, except with your username or student number.

$ ssh git@git.cs.sun.ac.za
Welcome to GitLab, @ajcollett!
Connection to git.cs.sun.ac.za closed.                     

Links¶