CS 725/825 Computer Networks, IT 725 Network Technology

CS GitLab Instructions

Overview

The course uses the version control system Git to submit the programing parts of the upcoming assignments. Program submissions outside of the repository will not be accepted and points will be taken for any repositories that do not follow the specified setup. You are expected to follow these instructions carefully. Uniform structure of student submissions simplifies the grading process. If anything is not clear or not working, ask on Piazza. All the files are hosted in a single Git repository. Each student uses a private repository, shared with the class instructor and grader. It is essential that the repository remain private at all times (not internal or public), as programming assignments must be worked on individually. (In this class, Git is not used for collaboration.) Theses instructions are based on a handout written by Prof. Michel Charpentier and appropriated here with permission.

If you used CS GitLab in other courses, including Prof. Charpentier's, the setup is slightly different. Make sure that you read and follow these instructions.

For those familiar with Git/GitLab, the objective of this handout is for a student whose UNH login is xxx to:

fork the GitLab project: git@gitlab.cs.unh.edu:cs725/cs725-f24.git into a project of the same name in your namespace: git@gitlab.cs.unh.edu:xxx/cs725-f24.git;
make this new project private;
add @cs725 as a project member in a Developer role;
clone the new project into repository on a development computer;
set git@gitlab.cs.unh.edu:cs725/cs725-f24.git as a remote of this repository in order to pull files added by the instructor.

For those who are new to Git, below are detailed instructions on how to achieve this.

Setting up a course GitLab project

Git repositories are hosted on the department’s GitLab server. You can log in the server at https://gitlab.cs.unh.edu/ (use the Wildcats tab, not the Standard tab). Using the web interface, your first task is to create a new project¹ by forking the template project git@gitlab.cs.unh.edu:cs725/cs725-f24.git.

This project can be found using “Explore (public) projects” on the web interface. (The project may not appear in the “Trending” or “Most stars” categories but should at least be in “All”.) Use the Fork button to create a new project (in your namespace).

The very first step you must do with the forked project is to make it private using the Settings → General → Permissions → menu. Expand Permissions and set Project visibility to Private. Don't forget to click on Save changes (you may need to scroll down to see the button). Do not not change other settings (especially the project name).

Sharing

Using the web interface (Settings → Members), add @cs725 (CS725 Admin) to the project and give it the Developer role so the project can be cloned by the instructor/grader.

Setting up local clones

The next step is to set up one or more computers where you plan to do development. You can setup several development computers (e.g., at home and at school), but be careful with commit/merge issues. The following steps must be repeated on each computer.

If this is your first project on CS GitLab, you need to setup an SSH key in order to update the project with your code. You will need a key on each computer from which you plan to access the repository. See https://gitlab.cs.unh.edu/help/user/ssh.md for details.

Access to Git repositories can be done using various Git clients, including GUIs and IDEs. Here we use a command-line client, git, which is available on all Unix computers (including MacOS):

First, use git to configure your name and email. This is important because Git uses email addresses as identifiants:

git config --global user.name "John Doe"
git config --global user.email "xxx@usnh.edu"

where John Doe is replaced with your actual name and xxx is your UNH login.

Then, clone the class repository (replace xxx with your UNH login):

git clone git@gitlab.cs.unh.edu:xxx/cs725-f24.git cs725

This creates a cs725 directory that will contain code and other resources (you can pick a different name). Change to that directory :

cd cs725

From here on, all the commands from this page are executed from within this directory.

Using Git, you will be able to pull provided files into this directory. For this to work, a relationship needs to be established between this new local repository and a shared source: the forked repository populated by the course instructor/TA. This can be achieved by executing the following command:

git remote add upstream git@gitlab.cs.unh.edu:cs725/cs725-f24.git

Your local repository has two roots: origin, where you push your code (including final submissions) and upstream, from which you pull instructor/grader files. You might also pull from origin, e.g., if you work from multiple places, but you never push into upstream (for which you do not have the necessary permissions anyway). You can check that the repository is correctly setup by executing git remote -v. This produces an output of the form:

origin  git@gitlab.cs.unh.edu:xxx/cs725-f24.git (fetch)
origin  git@gitlab.cs.unh.edu:xxx/cs725-f24.git (push)
upstream    git@gitlab.cs.unh.edu:cs725/cs725-f24.git (fetch)
upstream    git@gitlab.cs.unh.edu:cs725/cs725-f24.git (push)

After that, updates to your local repository will happen in one of two ways:

Adding your code. As you work to implement a programming assignment, you will add/modify code in the repository. These changes can be committed into the local repository (using commit) and then pushed onto the GitLab server. The repository where you push your own code is referred to in git commands by the name origin.

For instance, after implementing parts of an assignment, these steps would add the new code to the repository. Let's assume that you created file a1.py with an IDE or editor, then you need to add the file to the repository:
```
git add a1/a1.py
```
Them commit it locally:
```
git commit -m 'a1.py added to assignment 1.' 
```
And, finally, push onto the CS GitLab server
```
git push origin main 
```
Note that, of course, many files can be added/modified before they are committed, and many local commits can happen before files are sent back to the server.²
Adding/updating code produced by the instructor/grader. The instructor and the grader may add/modify files in the upstream repository you forked your project from (normally, files other than the files you work on). Bring these new/modified files into the repository by executing a pull from the upstream source:
```
git pull upstream main
```
This brings in all the new files (and modifications) that the instructor/grader generated.

Assignment submission

Assignments are submitted by tagging a specific commit in the Git repository and pushing the tag onto the GitLab server. After the assignment has been implemented and the implementation committed (git commit) as shown above, add a tag (a1 in this example) as follows:

git tag a1 -am "Assignment 1 submission"

The --tags option of push can be used to include tags when pushing onto the server:

git push --tags origin main

If changes are needed after an assignment has been submitted (but, of course, before the due date), you should create a new tag by adding a dot and an extension, e.g., a1.1, a1.2”, etc. The commit with the tag that has the largest minor version will be graded.

Repository layout

The repository is laid out as follows:

.
|-- .gitignore
|-- README.md
|-- a1
|   `-- README.md
|-- a2
|   `-- README.md
|-- a3
|   `-- README.md
|-- a4
|   `-- README.md
`-- a5
    `-- README.md

There is a directory for each of the assignments in the course. All files related to an assignment must be located in its directory. You are expected to edit the README.md files to include your name and email as well as any instruction for compiling and testing your submissions. A simple .gitignore file is included to prevent the most common computer-generated files from ending up in the repository. You can add to it but think twice before removing lines from it. Any suggestions on its content are welcome.

Your repository must remain private at all times, leaving the content the repository accessible to anyone other than the instructor, TA, and yourself will be considered as a violation of the rules of conduct and will have serious disciplinary consequences. If you are not sure whether you set up the access rights correctly, ask the instructor or the TA. If you discover that you can see the content of someone else's repository, inform the instructor or the TA. If this is a result of an honest mistake and it is promptly corrected, no disciplinary action will be taken.

You are encouraged to commit as you continue your development and you are expected that you commit/push your code before asking a question over email - yes, this may involve committing broken code, something that is not considered ok in practice, in our situation it helps us to see where you are.

Tools

There are many tools available to work with Git repositories, you are free to choose to one that works the best for you.

Command-line commands are available on most platforms, including agate.cs.unh.edu. There are many pages on the Internet that provide platform-specific installation instructions. If you are a MacOS user, I recommend installing Homebrew.

Most Integrated Development Environments (IDEs) and professional text editors have either built-in or installable support for Git. IDE support may depend on Git command line interface installed, check that if something is not working. While knowing at least the basics of command line Git is a critical skill, working with repositories through IDE may be an easier way to go forward. I recommend using IDEs by JetBrains.

There are several standalone GUI clients for Git that bridge the gap between the CLI and an IDE. The one that I recommend is SourceTree. It is a product of Atlassian and the installation may require that you create a free account.

New tools pop up every day. If you find something that helped you, share it with me or, even better, on Teams.

A GitLab project corresponds to a Git repository.↩
Push often to the server. “I lost all my code because my laptop died” is not a valid excuse.↩