Git and GitLab
Objectives
We shall learn how to use the modern code management system (CMS) Git to manage a software project. The base repository server is implemented using the GitLab API. Usage is granted by logging in with the ANU ID and the password. A project management is performed with Lightweight Directory Access Protocol (LDAP).
Logging in the GitLab
In order to manage and submit your assignments and some of your homework, you
need to create a git repository using our GitLab server. We shall treat all
such projects — Assignments One and Two, Homework 3, 7 and 8 — as one project
named comp6700-2017.
Note although the repository is named comp6700-2017
, it is intended for use
by students in both COMP6700 and COMP2140.
Creating the project
Using a web browser, log in to the ANU’s GitLab website. (Mind the presence of cecs
in the URL; the URL gitlab.anu.edu.au points to
another GitLab server which is used for research work). Choosing ANU ID
tab,
sign in using your normal ANU ID and password. Perform the search for project
name with comp6700-2017, or simply go to
When the project repository page opens, locate the Fork button, which looks like this:
to create your own copy which you should name using your Uni ID, such that the resulting URL will be
https://gitlab.cecs.anu.edu.au/u0123456/comp6700-2017.git
(where instead of u0123456
your actual ID number is used).
Wait… (should not be too long), until the project is created, a new webpage will open in which the name of the project is displayed:
git@gitlab.cecs.anu.edu.au:uXXXXXXX/comp6700-2017.git
with your actual ANU ID in place of uXXXXXXX
. This will the the master
repository URL. You can clone it to the computer of your choice (one or
several), use the cloned (aka, local) repository to work on your projects,
add new items, commit the changes to the cloned repository, and
push the local repository to master (the one you’ve just created), such
that the last push before the deadline, will constitute your submission.
Assuming that you are using the Unix/Linix command line, execute the two setting commands from the topmost “black box”
% git config --global user.name "Your Actual Name"
% git config --global user.email "uXXXXXXX@anu.edu.au"
(replace uXXXXXXX
on your ANU ID).
Making your project usable and useful
But before you do all cloning etc things, two more steps need to be taken:
-
Letting examiners to access code
To allow us (the lecturers and the tutor) a read access for marking, you need to add us as Reporter members of your project. Failure to do this will prevent us from cloning your repository and marking it.
Return back to the project webpage (
https://gitlab.cecs.anu.edu.au/uXXXXXXX/comp6700-2017
), and click on “Settings” Link (top right). On the “Project Settings” page, click on Members link (left)on the then opened page “Users with access to this project” (you should see yourself there until this moment the sole member), click on the Add users to project button, then your tutor, Alexei and Josh (lecturers and tutors) in the form “People”, and choose the access level “Reporter” – this will give us (and only us) the read access to your master repository.
-
Creating and adding the public ssh-key
To facilitate the data exchange during cloning, pushing and pulling (when you update the local repository to synchronise it with changed state of the master repository – this operation is analogue of pushing, but the data flows from the remote master to the local), you need (if you have not done it already) to generate a public ssh-key (if you want to clone more than one local repository on different computers, eg on a personal laptop and on your lab computer, this procedure must be repeated on each machine). Every Unix/Linux OS has this functionality by default.
Still on the new project webpage, observe the right side of the top bar, find the “Profile setting” icon
and click on it. This will lead your to the “Profile setting” page, which will already contain your name and email. Click on the link SSH Keys at the top (right under the search box). This will open the “My SSH keys” (which should be empty). Click on the
Add SSH Key
button, it will open another page, “Add an SSH Key”, with two forms:-
“Title” – choose the machine name to which you will be cloning the master repository and from which you copy-and-paste the ssh-key, as described below; if you’re using your CS account, use the name “partch”
-
“Key” – paste there your ssh-key.
How to get the ssh-key?
-
If you have already generated a public ssh-key: run the listing command on the ssh-directory (dot is important!)
% ls -l ~/.ssh
if the output contains a file
id_rsa.pub
, see its contents by running the commandcat ~/.ssh/id_rsa.pub
, it should display a long string of characters which begins with either ssh-rsa or ssh-dsa. This is your ssh-key, paste and copy it to the “Key” form (on the “Add an SSH Key” page). -
If the
~/.ssh/id_rsa.pub
file (or, likely, the ssh directory~/.ssh
) doesn’t exist, you will need to create one. Run the command on the terminal:% ssh-keygen -t rsa -C uXXXXXXXX@anu.edu.au
(providing your actual working email, the same you used when configuring Git), and it will create the
~/.ssh/id_rsa.pub
file (and others too, but they are of no interest here). You will be asked to type a passphrase – choose either empty string (just hitreturn
without typing anything), or type in something you can remeber well. Now runcat ~/.ssh/id_rsa.pub
will display a string like described in the previous case. This is your ssh-key, paste and copy it to the “Key” form (on the “Add an SSH Key” page).
-
Now we are all set to clone a local repository.
Cloning a local repository
On the same machine from which the ssh-key was chosen, create (somewhere
convenient) a directory comp6700-2017
, change into it, and run the command:
% git clone git@gitlab.cecs.anu.edu.au:uXXXXXXX/comp6700-2017.git
(the cloning can also be done from within an IDE, like IntelliJ, or an editor,
like Atom – we will demonstrate this in the lectures, or ask your tutors for
help if necessary).
This will create a local repository in the directory – in which you have to
change – comp6700-2017
that has the same content as the forked repository on
the Gitlab server – the directories and the file README.md
.
README.md
ass1
ass2
homework
some directories contain more files and subdirectories depending on the task.
When assignments are released with
associated code and data, you will have to add them to relevant directory and
bring them under the Git management (by using the command git add
).
Modifying and adding items in a repository
The Git tool has several standard command to manage your working repository.
By running the command git status
, you can see which items are currently
modified, added or removed from the project. If you have not changed an
existing file or added a new one, the git status
will tell you are
“up-to-date”. Try to modify README.md
file (for instance, that you’ve read it
and now stared working on the assignment One). Run git status
again and
observe the different output.
Now change into homework/hw3
directory (where a supplementary code of the
Homework Three is located), compile the code and generate its documentation by
running these two commands
% make compile
% make doc
and observe the output of git status – it will tell you that now there’re
untracked files and suggest that you use git add to included them to the items
which you can commit for the next version of the project. But do not run
git add .
just yet – not every newly created file needs to be part of a
project. Run
% make run
to observes the application execution. Study the documentation (open the file docs/index.html in a browser), it will help you to understand the structure of the original code. If you like, you can later remove all generated files by running the command
% make clean
Committing changes to local repository
When you’ve modified items which are part of the project or created new ones
and added them by using git add *items*
command (if you want to add every new
file, just say git add .
), you can commit them to the new revision
git commit . -m"log message"
what goes after -m
option is a log entry. It is important to provide a short
and informative log entry with every commit you make. The dot after commit
means everything which is being tracked by git (as reported by git status
);
if you want to commit only some of those tracked items, use their name
explicitly, or using wild card &mash; when you are ready to commit homework or
assignment files but not anything else (even though those other items have
changed, too), run (for example, to commit you homework 4 code):
git commit hw4/* -m"log message for hw4 (be brief)"
Pushing your local repository to the remote (“submitting”)
When in the process of your work, you have made several commits, and completed, say, the homework 4, it’s time to submit it. The submission will be performed by sending the content of the local repository to the master (your forked repository on Gitlab). Git does it with the push command:
git push
And that’s it!
All basic Git procedures can be performed from within an IDE (like Idea, and we demonstrate this in our lectures), or from within a modern programming editor (which may or may not need installation of special plugins).
Once a GitLab repository is created (and ssh-key added), you can also use a GUI-client (instead of the command line, or an application like an IDE or an editor). All three major OSes have a few such clients (some of them open source and/or free). To name the few:
You will undoubtedly need additional tutorials and instructions to get familiar enough and comfortable enough with Git. Do a search for “git tutorial” and it will bring you a lot of results (too many – Git is a very popular tool). Ask for advice which resource to use, check references in the P3 lecture, or, perhaps, check out this free online book and a blog post:
- Conversational Git
- Git from the inside out
- TryGit — HitHub’s tutorial which runs entirely on the server (you run no risk of messing up own file system)