IC470, Software Engineering
Lab 5

Due: As per the course syllabus

Lab Focus:The Git version control system, and USNA's GitLab server

Lab Partners:You are to work alone on this lab (but may freely ask each other questions and lend assistance)

Deliverables:A graph showing all the changes, branching, and merging activity that you completed will be available from the GitLab system once you have finished the lab.

Intro to Git

Working on a capstone project sometimes means two or more folks huddled around one keyboard, but often it means doing a little planning as a team, and then going off to separate computers to work on different components of your project. This kind of collaboration is greatly enhanced by using version control systems such as Git for tracking changes in computer files and coordinating work on those files amongst multiple people. Git is primarily used for source-code management in software development, but it can be used to keep track of changes in any set of files.

Git manages the process of pulling updated code from colleagues, pushing the updates you make to the code so others get it, and tracking changes to projects over time. Git is also useful if you work on your project from different locations, like from a lab computer or your laptop in Bancroft Hall.

The CS Dept runs a GitLab server as a host for you and your classmates to create and share projects for collaborative work. This is a central repository of all the files you and/or your team will be creating and working on. Each of you will checkout ("clone" in Git parlance) the repository in a convenient place in your own home directories, and periodically "push" the changes you've made to the repository, and "pull" the changes your team has made from the repository.

Initial GitLab Access

Note: The next three Steps only need to be completed once for your profile at USNA. Under normal circumstances you'll never have to do these steps again. If you are already a USNA GitLab user, you can skip to the Creating a Repository section.

Account Creation

  1. Go to: https://gitlab.usna.edu/. Click on "Register" and fill out the information. Use your ALPHACODE as your USERNAME!
  2. Open your email application, look for the registration confirmation, and follow the instructions in the email.
  3. Return to: https://gitlab.usna.edu/ and sign in with the username and password you used in Step 1.
    NOTE: this password is NOT linked to your USNA account. It will not change when you change your USNA password.

Set up SSH to work with GitLab at USNA

  1. If you are familiar with using SSH keys to connect to other systems, then skip this step. Otherwise, open a terminal window to your home folder and then edit and execute the following: 
    ssh-keygen -o -t rsa -C "your_email@usna.edu" -b 4096
  2. Run and copy the output from the below command. Be sure to copy everything from the "ssh-rsa" to your email address. 
    cat ~/.ssh/id_rsa.pub
  3. Open this link and paste the copied SSH key into the box. Click the "Add key" button.
  4. Once you have successfully added a key to your profile, then you will receive a confirmation email. You may delete this email. If you didn't receive it, then you didn't complete the step properly.
  5. Test it by running the below command and verify that you receive a stream of text that ends with "Welcome to GitLab, @username!". If you don't, then you have done something wrong (hint: If it hangs or you get prompted to enter a password, the problem is likely with your SSH key, so go back and repeat the above 4 steps exactly as described). 
    ssh -T git@gitlab.usna.edu

Finish your Git profile setup

  1. Copy the lines below, leave the quotation marks alone, edit the red text accordingly, and run them in a terminal window.
    git config --global user.name "Your Name"
git config --global user.email "your_email@usna.edu"

Creating a Repository

Create a New Project

  1. In the top menu, go to "Projects -> Your Projects". Click the green "New project" button.
  2. Pick a project name.
  3. Put the project name in the associated blank on the form, leave the Visibility Level set to Private, and click the green "Create project" button.
  4. You should see a blue banner that states your project was successfully created, and you are now on your project's details page.

Add Members to your Project

  1. Do the following for each member of your capstone team in this section (pick someone else in the section if you're solo). They will get an email which they can safely ignore for the purposes of this lab.
  2. To add a member to your project, from the left menu, click/hover on Settings, then click on Members.
  3. Under Select members to invite, start typing your team member's name or alphacode and select their name when it pops up. Repeat this process for each person you want to add to the project.
  4. Under Choose a role permission, choose Maintainer.
  5. Click the green "Add to project" button. Your team members will each receive an email with a link to the project page.

Working with the Repository

Get a local copy of the Project

  1. From a terminal window, create and navigate to a folder for this course. Something like: 
    cd ~/ic470/labs/
  2. DO NOT create an additional sub-folder for this specific lab. If you did so, remove it now.
  3. Copy the git clone command line from the project page, and run it in the terminal window. It will look something like this: 
    git clone git@gitlab.usna.edu:ic470-mYourAlphaCode/projectName.git
    or this if you're a team member on someone else's project: 
    git clone git@gitlab.usna.edu:mTheirAlphaCode/ic470-mTheirAlphaCode/projectName.git
  4. At this point you will all have an empty copy of the project contained within a new folder inside your ~/ic470/labs folder.
  5. From your terminal window, change into the project directory. 
    cd projectName

Initial Push

  1. Run the following commands to create an empty README file and push it to the project repository: 
    touch README.md
git add README.md
git commit -m "add README"
git push -u origin master

Initial Pull (as required for Team Members or from another computer)

  1. Run the following command:
    git pull
  2. You should have seen some output indicating that the README file was downloaded, and now if you run the ls command you should see the file in your directory.

Get to developing!

  1. Add files (to track them). As each team member creates files, you will need to add the file as part of the repository. The add command does not actually insert the file into the repository, but tells git that that you want to add it to the index. Whenever you make changes to a file that you want reflected in the repository, you must add the file for those changes to be staged for the next upload. Let's try this out by creating two files (file1 and file2) using your favorite editor (they can be empty files), then add them to your repository: 
    git add file1 file2
  2. Committing and Pushing your files (or changes to existing files) to the repository. To actually commit your changes and provide a message for the things you changed, use: 

    git commit -m "Description of what you did"
    [master 50ec910] Description of what you did
   2 files changed, 7 insertions(+)
   create mode 100644 file1
   create mode 100644 file2
    The file is now committed to the HEAD of your local working copy, but has not been pushed to the repository! To send your local working copy to the remote (master) repository run: 
    git push
    Counting objects: 4, done.
  Delta compression using up to 8 threads.
  Compressing objects: 100% (2/2), done.
  Writing objects: 100% (4/4), 353 bytes | 0 bytes/s, done.
  Total 4 (delta 0), reused 0 (delta 0)
  To /--your-groups-location--/
     9f93140..50ec910  master -> master
  3. Pulling code from the repository. To get changes from the repository (such as when your team members add important updates) you will want to pull those changes into your local working copy using: 
    git pull

Checking on the Status and Changes

If you would like to see what files have changed since your last commit/pull, run the command 

git status
To see exactly what's changed in a file you've modified, 
git diff fileName
... and git will show you (in "diff" syntax) what's changed.

Getting More Advanced

Now that you have the basics, continue the lab by completing the lesson on Git Branches and Merging: https://gitlab.usna.edu/ic470/branch_and_merge_exercise A graph showing all the changes, branching, and merging activity that you completed will be available from the GitLab system once you have finished the branch_and_merge_excercise.

Additional Tutorials

There are many excellent tutorials online that can provide additional information on how to use git, and many of the more advanced features. The following link is one such source that delves into more advanced features. http://www.vogella.com/tutorials/Git/article.html