How to use GitKraken
Goal: Be able to clone your project (to download it from GitLab), to edit it locally,and to save your changes to your local git repo and to the GitLab server.
In this exercise you will download your copy (including those changes) and you will continue to modify it.
You must finish the previous exercises first so that the changes you make at the end of those exercises will be downloaded in the this exercise.
You're expected to try and make progress even if the pictures aren't identical (just like you'll be expected to first try and fix your own problem when working in industry). As always, if you get stuck please seek help from the instructor.
(If the images below are wildly different from what you're seeing please contact the instructor - it may be that something big has changed since this tutorial was created)
What you need
In order to do this exercise you must have already done:
-
Log in to our private GitLab server
You need to know your username and password for this tutorial!
When your accounts are created in GitLab the server will email you a link that you can click to get into GitLab directly. Make sure that you note your username, and then set (or recover) your password so that you can tell GitKraken how to log into GitLab for you.
all of which was covered in the prior tutorials.
What you'll do in this tutorial
There's several steps to working on your git repo on your local (personal) computer:
-
Clone the project/repo to your machine from the GitLab server, using GitKraken
-
Commit your change(s) to your local git repo using GitKraken
-
Push the commit (the saved changed) back to the GitLab server
Installing GitKraken
In this course I recommend that you use a program named "GitKraken", made by a company called "Axosoft". The Axosoft GitKraken program is nice because it has a graphical user interface (it has windows, menu bars, etc), it's available for Windows, MacOS and Linux, and it's free. That said, you're free to use any other git client you want as long as you're comfortable trouble-shooting your problems independently.
The first step is to download (and install) the program. You can do this at https://www.gitkraken.com/. Once you've installed the program start it up.
GitKraken uses the git "protocol" to do it's job. It does this by actually using the git software (instead of using it's own, internal, implementation of the git "protocol"). This means that you can install GitKraken, but if you don't install the git software that GitKraken uses then GitKraken can't work.
What does this mean for you? During the instalation process GitKraken may ask you if you'd like to install some git software. You should say 'Yes' and install that git software so that GitKraken can use it. If GitKraken offers to install anything else (for example, the PuTTY-Keygen program, which Windows users can use to generate keys for the SSH protocol) you should also install those programs as well.
If GitKraken does not offer to install any additional software then that's fine too - either you installed it previously or else GitKraken doesn't need it.
Cloning (copying) the project (repo) from GitLab to your computer
When you first start GitKraken it will probably look something like this:
(You'll probably see something slightly different - my GitKraken already has a project/repo open in the background that I can't figure out how to close)
The main thing you'll notice is a dialog box in the middle of your GitKraken window (outlined in red, above). GitKraken would like you to sign into an established 'git' server - in this case either GitHub or their own GitKraken server account. You may need to do this later, but we're going to skip this step for now - close this dialog box by clicking the 'X' in the top-right corner (where the arrows are pointing to).
At this point you use the File >> Clone Repo menu option to download your project/repo from the GitLab server, as shown here:
When you click on that button and the contents of the GitKraken window will change so that it looks like the following:
First, make sure that you're looking at the right tab - make sure that you're looking at the 'Clone' tab indicated by the box with '1' in it in the above picture. (GitKraken should choose this by default, but it doesn't hurt to double-check)
Next, make sure that you're cloing a repo from it's URL, by clicking on the 'URL' in box #2 in the above picture.
You need to fill in the 'Where to clone to' box and the 'URL' box.
The 'Destination Path' box is the easier one - it's Box #3 in the above picture, and it's where you'll put the path to a folder on your local hard drive where the project should be cloned to (copied to). If you click on the button with the "Browse" button then it will open up a normal 'File Open' dialog and you can find a good folder through there.
By default GitKraken will put your new project/repo into a list of bookmarks, in order to make it easier to find later (this is the '3' arrow). This seems harmless and can be useful, so leave it checked off.
The 'Source Path / URL' box is slightly trickier (in box 4) - you need to go back to the GitLab web page for the project you wish to clone and copy something from there.
Open up a browser window, and navigate back to the GitLab web page for the project. It should look something like this:
The first thing you need to do is to pick either the default HTTP option or the HTTPS option from the drop-down list pointed to by the '1' (either option puts the same string into box #2.
The second thing you need to do is to copy the blob of text pointed to by the '2' (in the above picture it starts with 'http://ccc-git-lab-server...'). This is the Source URL that we need.
If you want to you can click on the icon pointed to by the '3', which will copy the source URL for you.
Once you've gotten that information paste it into the 'URL' box in the previous picture, at which point you'll see a new line appear. The Full Path line can be ignored (the defaults are fine), and then your window should look similar to this:
At this point you can click the 'Clone the repo!' button (which is now active- the arrows in the above picture point to this)
GitKraken will ask for your GitLab username and password. Your username is listed in the bottom corner of the web page (in the above image the username is "Testy_McTest".). You need to type your username and password into the top of GitKraken. Look carefully for the username (box 1, below) and password (box 2) boxes because they're almost invisible in the default, dark color scheme. Once you've typed them in you can click on the green Log In button.
You'll need to use the same username and login that you use to log in to GitLab.
Once this works you'll see a confirmation message. You should click on Open Now:
You then forked a second copy, on the GitLab server. This was your own, personal copy, and you can change it.
At this point you've now cloned a third copy onto your local computer. This is good because you can compile and run it on your computer (which you can't do on the server, even on your own copy).
It can be confusing to have three separate copies of the same project; it's good to periodically stop and think about which version you're currently workinog on in order to avoid that confusion.
It may help to think of the copies like this:
- The Administrator's copy (the teacher's copy) exists only so you can copy it. You can't change this, so don't try to do work here.
- Since you're allowed to change this copy this is where you'll
put your work, once you're ready for it to be graded.
The teacher can see your copy on GitLab; the teacher will grade your work by examining what you've uploaded to GitLab. - The copy you have on your computer is the copy that you actually work on using Visual Studio.
At this point GitKraken will look something like the following:
This tells you that GitKraken was able to succesfully clone (copy) the repo (project) from the GitLab server to your local computer. It's good to explore the program a bit, and see what information it tells you (and to remember anything that seems particularly useful).
The next step is to make a change to the project itself. You can do that by opening up the Visual Studio project in Visual Studio (and/or Windows Explorer) yourself. If you forget where you put it you can find it again by clicking on the master tab in the left hand column (in the '1' box in the below picture- you may need to click on the LOCAL tab in order to show the master tab), and then click on anything listed in the main panel. We'll click on the First Commit! item (in box 2, below):
Once you've clicked on First Commit! (or any of the other options) you should see a list of files in the bottom-right panel. You can then right-click on any of the files to see a context menu, including our goal: the Show in folder menu item.
This will open up the folder in your normal file browser; from there you can copy the path to the folder.
Note: If you accidentally left-click on the file you'll be shown the contents of the file, like so:
You can see the contents of the file in box 1, and you'll notice that the stuff that used to be in that panel is now a column of icons just to the left of the file.
You can (and should!) close the file viewer by clicking the X at the top-left of the file viewer box (in box 2, in the above picture).
Change the project using Visual Studio
Let's say that we've opened the project in Visual Studio (and then opened the Program.cs file) and we're looking at a program like this:
Imagine that we change the program so that it looks like this:
At this point we're happy with this change and so we want to store it back onto the GitLab server so that the teacher can grade it. We can do this via two steps:
- committing our changes to our local repo on our personal computer's hard drive, then
- pushing the changes back up to the GitLab server
Commit your change(s) to your local git repo using GitKraken
We can commit our changes to the local git repo by using GitKraken. You should leave Visual Studio (making sure to save all your files first!) and go back to GitKraken.
In this example, you would see the following:
We need to notice that the top line now says "WIP:master" on the left
edge of the red box (in the above picture). WIP stands for Work In
Progress, and refers to any changes you've made that you haven't yet saved
into GitKraken. You need to then click on the yellow square
that's found in box 1 of the above image.
Unfortunately this is
all very easy to miss, so please look carefully.
(Also -
you will need to close the file viewer box
if you happen to have it open)
(If you don't see the WIP: line after
closing the file viewer then try to scroll that panel upwards, and see if
you can find it then.)
After you've clicked on the yellow box you'll see something like this:
In the middle of the window is a panel labeled 'Unstaged files' (box 1). Since the only file we changed was Program.cs that's the only file that's listed here. If you click on it you'll see the contents of the file appear on the above it (box 3). Notice that the pretty picture we were looking at get squished down into a column of icons (box 2). If you click on the file in box 1 a second time it will hide the file contents and show you the pretty picture again.
If you examine the file in the above picture (box 3) you'll notice that it's actually trying to show you how the file has been changed. Lines that are highlighted in red and have a minus sign at left edge are lines that have been removed. Lines highlighted in green with an addition sign (a plus sign) at the left are new lines. When we change a line it's represented as the old line being deleted and the modified line being added. You can see this on line 9, where we changed it from
Console.WriteLine("Hello, World!");to
Console.WriteLine("Hi, git!");In order to commit (save) our changes we must first tell git which changes we want to save (commit). We do this in the GitKraken program by either clicking 'Stage all changes' (if we want to save all of our files) or by selecting individual files and then clicking on 'Stage File' (box 4, in the above picture).
You'll notice that the Program.cs file moved from the 'Unstaged files'
list to the 'Staged files' list (box 5). A 'Staged file' is
a file that git will save (commit), once we tell it to do so. By
allowing us to separately stage, and then commit (save) our files we could
very carefully commit only a couple of our files if we wanted to. (In
this class it's recommended that you stage all your files so you don't
accidentally leave anything out).
You can click on the 'Program.cs' file
in the 'Staged files' list and again see the file (with changed
highlighted).
Just like with GitLab you must write a commit message before you're allowed to commit you change. You can do that by filling in box 6 (above). Once you've written a Commit Message the Commit button will be activated (in box 7 - note that the button in box 7 will be inactive and display a message telling you what you need to do next until you've done everything that GitKraken needs you to do).
Luckily for us GitKraken will show the new changes to the file in the 'Unstaged files' list (and it will show the earlier changes that you staged in the 'Staged files' list, which may be confusing).
The main lesson here is that if you stage a file (thus adding a copy of that particular version to git), then go back and change the file you'll need to stage it again before you commit it.
Another strategy that works well in this class is to always stage and then immediately commit your changes (thus preventing you from changing a previously staged file)
Push the commit (the saved changed) back to the GitLab server
At this point we've saved our changes into git's copy of our local repo (our project on our computer). However, we have not updated the server yet. GitKraken even tells us this, as shown in the following picture:
The top line (box 1) in the GitKraken window contains the commit message
that we just added in the prior step, and so it's clearly the commit that we
just made. At the left edge of the box we can see the word 'master',
and a picture that looks like:
This icon is GitKraken's icon for our local computer. In sum, this
line tells us that your commit is stored on you local computer (i.e., the
one you're using).
In box 2 we see the word 'master' again, but a different icon:
.
This icon is GitKraken's icon for the GitLab server (also called a 'remote
computer'). This line tells us that the latest commit stored on the
GitLab server has the commit message that starts with "All notes in this
file...".
Because our local commit is located above the latest commit on the GItLab server we know that we've made changes to our local repo/project that are NOT YET stored on the GitLab server. Whenever you do a commit you should get used to checking for this just so that you'll know to check this when you accidentally forget to upload your changes back to the server.
In order to upload our changes to the server we need to click on the 'Push' button, in box 1 below:
(If you want to find out what any of these buttons do you can hover your mouse over the button, wait for a bit, and GitKraken will tell you the name of the button. From there you might try searching the web. For this button you might try both "GitKraken push" and just plain "git push" and see what you get.)
GitKraken will briefly display a message on your screen telling you that the push succeeded (box 1, below). After the message disappears you'll know that things are ok because you can see both the local and remote icons next to each other (box 2, below)
Confirm that the changes are on the server
In order to confirm that your changes really did make it back to the server you should go back to the GitLab web site, then find the main page for your project/repo, then click on the 'Files' link in the left-hand column, in order to see something like this:
In order to confirm that the commit was successfully pushed back to the server we'll look at the contents of the file itself.
However, before we look at the file contents we can already see two clues that the commit worked. First, you'll notice that the second column in the files table lists the 'Last Update', and that Program.cs was updated recently (this is above the '1' arrow)(the reason why it says 'about an hour ago' is because I took a break from writing this and did some other work for about an hour). Second, you can see the Commit Message in the last column (above the '2' arrow).
However, there's nothing quite as reassuring as seeing the newly updated contents of the file itself. Click on the word 'Program.cs' and you'll see something like this:
This does look like the changed file that saved so we know that we were able to save our changes successfully.
What to do if the changes AREN'T on the server
If you looked on GitLab and didn't find your changes then you should start by retracing your steps.
- Make sure that you made the changes in Visual Studio, and make sure that you saved them.
- If the changes were made and saved then the next step is to see what GitKraken says about the project. The file is listed in the Unstaged files list then you should stage it and then commit and push them.
- If it's listed in the Staged files list then commit and push them.
- If you see your commit message listed on the top line (along with the 'local' icon) but you see the 'remote' icon a couple of lines down then try pushing the changes.
After troubleshooting you should of course go back and confirm that the commit is on the server now.
If you saw an error message at any point during this process you should go back, get the error to happen again (if you can), and then copy that error message into Google/Bing and see if anyone else has fixed that problem.
If that doesn't work then post a question to an appropriate discussion forum on Canvas and/or email your instructor for help.
Getting your grades from GitLab
At this point the plan is that the instructor will grade your work by cloning your GitLab repo to their local computer, grading the work you did, writing feedback into a file, committing that file to their local repo, and then pushing that new file back to your repository. (You might notice that in this plan the teacher skips forking your repo - the teacher can do this because the teacher is the GitLab Administrator, and the Administrator account is allowed to access everyones' projects)
If you want to view your feedback you'll need to wait until the teacher has finished grading your work (at which point the instructor notify the class). You can then view the file on GitLab (this might not work for files like Word .DOC/.DOCX files or .PDFs), you can download a copy of all the files (using the "Download zip" button in the top-right corner of the project's file list, or you can download the changes to your local git repo by opening up GitKraken and clicking on the 'Pull' button (NOT the 'Fetch' button), agreeing to the reasonable defaults, and clicking 'OK'.