Introductory Programming in Java

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

COMP6700-2017

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:

  1. “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”

  2. “Key” – paste there your ssh-key.

  How to get the ssh-key?

  1. 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 command cat ~/.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).

  2. 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 hit return without typing anything), or type in something you can remeber well. Now run cat ~/.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:

• GitX (OS X)
• Git Extensions (windowz)
• git-cola (all platforms)
• a few others

---

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)