How to use Elegit
Goal: Be able to clone your project (to download it from GitHub), to edit it locally,and to save your changes to your local git repo and then upload those changes back to the GitHub 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 GitHub server
You need to know your username and password for this tutorial!
When your accounts are created in GitHub the server will email you a link that you can click to get into GitHub directly. Make sure that you note your username, and then set (or recover) your password so that you can tell Elegit how to log into GitHub 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 GitHub server, using Elegit
-
Push the commit (the saved changed) back to the GitHub server
Installing Elegit
In this course I recommend that you use a program named "Elegit", which is an open-source program created by a team lead by Prof. Dave Musicant at Carleton College. The Elegit program is nice because it has a graphical user interface (it has windows, menu bars, etc), because it's available for Windows, MacOS and Linux, because it's free, and because it's specifically designed to help students learn how git works. 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 http://elegit.org/. Notice that the file for the Windows OS that you're downloading is actually a .ZIP file (as opposed to an installer program) so you can 'install' it on Windows by simply extracting the .ZIP file and running the Elegit.exe program.
NOTE: You can download, extract, and run the program on the school's computers. This is good because Elegit is NOT installed on the school's computers. However, you'll need to use this link to install onto the school's computers because the school uses 32 bit computers (even the VMs) and the Windows .ZIP on elegit.org is a 64 bit version (which does NOT run on the school's computers - only the 32 bit version runs on the school's computers).
Elegit 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 Elegit, but if you don't install the git software that Elegit uses then Elegit can't work.
Fix this by installing my 32 bit version of Elegit.zip
Cloning (copying) the project (repo) from GitHub to your computer
When you first start Elegit it will probably look something like this:
(You'll probably see something slightly different - my Elegit already has a project/repo open in the background that I can't figure out how to close)
At this point you use the Repository >> Clone >> clone menu option to download your project/repo from the GitHub server, as shown here:
When you click on that button and the contents of the Elegit window will change so that it looks like the following:
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 'Enclosing folder' and 'Repository name' boxes and the 'URL' box.
The 'Enclosing folder' and 'Repository name' boxes are the easier ones - the 'Enclosing folder' box is 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 "Open Folder" icon then it will open up a normal 'File Open' dialog and you can find a good folder through there. The 'Repository name' box is the name of a subfolder the Elegit will create for you (within the 'Enclosing folder') to actually put all the stuff that it downloads from GitHub.
The 'Remote URL' box is slightly trickier - you need to go back to the GitHub web page for the project you wish to clone and copy something from there.
Open up a browser window, and navigate back to the GitHub web page for the repo. It should look something like this:
The first thing you need to do is to click on the button labeled "Clone or download" (the '1' arrow points to this green button in the above image).
The next thing to do is to copy the text that starts with https://github.com/..... You can do this by clicking on the 'copy to clipboard' button (pointed to by the 2 in the above picture)
Once you've gotten that information paste it into the 'Remote URL' box in the previous picture, at which point you can then click the 'Clone' button. You will then see this dialog box:
This is Elegit asking for your GitHub username and password. You need to type your username and password for GitHub into this Elegit dialog box. Once you've typed them in you can click on the green Authorize button and Elegit will try to clone your repo (will try to copy your repo from the GitHub.com server to your local computer).
You then forked a second copy, on the GitHub 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 GitHub; the teacher will grade your work by examining what you've uploaded to GitHub. - The copy you have on your computer is the copy that you actually work on using Visual Studio.
At this point Elegit will look something like the following:
The first thing to look for is your choosen repo name (pointed to by the '1', above). Notice that this is the same thing that you typed into the 'Respository Name' box in the previous step. If you open a second repo Elegit will show you that repo (instead of the current one) but you can get back to any repo that Elegit has previously opened by clicking on this button and selecting whichever repo you want to look at.
You'll notice that there's a list of boxes/triangles in the main window; each shape represents a single commit that you've made (either in GitHub or here in Elegit). If you move your mouse over one them (such as the one pointed to by the '2', above) then that dark box with white letters will appear. The box describes the commit -you'll notice that it contains the commit message that you entered while we were changing things on GitHub.
If you click on the shape then the right-hand column, labled "Commit info" (and pointed to by the '3', above) will also display that same commit info. Again, notice in particular the commit message, which is the same message that we entered on GitHub.
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 the repo you can find it again by clicking on the "Open repository directory" button near the top-left of the window, and which is pointed to by the '4', above. If you forget which one it is you can move the mouse over it (and all the other buttons) and the button's name will appear after a couple of seconds.
This will open up the folder in your normal file browser; from there you can copy the path to the folder.
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 GitHub 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 GitHub server
For example, after you've finished an exercise for this course you should commit your work. Each time you commit your changes you're saving a backup of those changes - and more backups is (generally) better.
Commit your change(s) to your local git repo using Elegit
We can commit our changes to the local git repo by using Elegit. You should leave Visual Studio (making sure to save all your files first!) and go back to Elegit.
In this example, you would see the following:
If you're not seeing the image above then double-check that you've got the correct repo open ("Lesson 01", in the top-left box) and that you're looking at the "Working Tree" (sometimes called the Working Copy)(you can show the working tree by clicking on the tab in the lower box).
In the left column of the window is a panel labeled 'Working Tree'. Since the only file we changed was Program.cs that's the only file that's listed here; as you can see it's clearly labeled as being "MODIFIED".
If you're interested in all the files in your working directory you can click on the tab labeled "All Files" (inside the box in the below image), and you'll see:
The '1' in the above image points to the Program.cs file, which is still clearly identified as 'MODIFIED'. You can see all the other files that are already present in the repo and have not been modified (such as TestUpload.txt, or TestWordDoc.docx). Additionally, you can see three directories - bin, obj, and .vs - which Visual Studio created in order to build the executable program that you run. Since these are generated from the Solution and source code files we don't want to include them in our git repo so we've told git to ignore them. (The instructions to ignore these files are located in the .gitignore file - feel free to look around in the file but please don't remove anything that's there). Elegit helpfully labels those directories as being IGNORE'd.
In order to commit (save) our changes we must first tell git which changes we want to save (commit). We do this in the Elegit program by either clicking 'select all' checkbox if we want to save all of our files (which is underneath the bottom red box in the above picture) or by selecting individual files and then clicking on the individual check boxes if we only want to save specific files.
In general you should save all the files that have been changed (unless you have a specific reason to leave some out).
At this point you should try to click on the 'commit' button, which is
near the top of the window (pointed to by the '1' in the below picture).
(I made the image smaller by removing some irrelevant stuff in the middle -
that's the red line with the 'snip' above it)
When you do this nothing will happen except that you'll see an error message appear in the lower-right corner of the window ('2', above). The error message tells us that we need to add the files before committing.
The primary goal of Elegit is to teach you how git works, and git requires you to 'stage' a file before committing (permanently saving) that file into git.
If you click the 'Add' button ('3', in the image above) then you'll see the following in the image below. Notice that the file is now listed as STAGED (the '1' arrow points to this). At this point you can commit you change(s) by clicking the Commit button (pointed to by the '2' arrow).
Luckily for us Elegit 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)
Just like with GitHub 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 Elegit needs you to do).
Here's how it looks:
Push the commit (the saved changed) back to the GitHub 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. Elegit even tells us this, as shown in the following picture:
The top line (box 1) in the Elegit 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 Elegit'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 Elegit's icon for the GitHub server (also called a 'remote
computer'). This line tells us that the latest commit stored on the
GitHub 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 GitHub server we know that we've made changes to our local repo/project that are NOT YET stored on the GitHub 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 Elegit will tell you the name of the button. From there you might try searching the web. For this button you might try both "Elegit push" and just plain "git push" and see what you get.)
Elegit 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 GitHub 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 GitHub 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 Elegit 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 GitHub
At this point the plan is that the instructor will grade your work by cloning your GitHub 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 GitHub 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 GitHub (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 Elegit and clicking on the 'Pull' button (NOT the 'Fetch' button), agreeing to the reasonable defaults, and clicking 'OK'.