CompSci 307 : Spring 2019

GITing Started

Knowing how to use a source control system will be an invaluable tool for you going forward, perhaps personally, but especially in a team setting. At its heart, version control is just a way to manage the many changes that occur to your files over time, but that simple idea changes everything! It allows you to revisit previous versions of your code, work with different versions at the same time, and work in teams and track who made which changes. At its best, version control is like a journal that you use to track major, and minor, events in your project. At its most practical, it is like a backup system that prevents you from losing significant work if something happens to your machine. At its worst, it is simply a submit system where you only track your work when told to.

Version control systems have been around for over forty years and GIT is currently the cool tool to use (partly because it was created by Linus Torvalds, the creator of Linux, and partly because of the popularity of GitHub, the largest public repository of code). Using source control well is not difficult, but it does take some practice and a little bit of command-line savvy (we do not suggest using visual GIT tools, even the one built into IntelliJ, until you are confident in your version control skills).

When running these programs, unless otherwise noted, we suggest following the default options.

Install GIT

Download and install GIT
on Mac or Linux, you can use the built in Terminal program to interact with GIT
on Windows, it comes with a program called Git Shell that you can use to enter the commands below (or you can install a full version of Ubuntu Linux!)
Within Terminal/Shell, configure GIT for your computer (note, these commands need to be done once for each computer you program on)
```
    git config --global user.name "YOUR NAME"
    git config --global user.email "NETID@duke.edu"
```

Login to Gitlab

Within a Browser, go to the our Gitlab site: https://coursework.cs.duke.edu/
Press the Shibboleth button to log in using your Duke NetID
After you have successfully been logged in through Duke's standard log in page, there may be a warning at the top of the page saying you need to set up an SSH key.
If not, click on your avatar icon in the top right corner -> Settings-> SSH Keys to set it up if you have never used our Gitlab site or if you are using this service for the first time from your current computer.
Clicking on that link should take you to a page prompting you to paste the public part of SSH key into the given text area
Next, we will get that public key

Generate an SSH Key

Within a Browser, go to the website: https://coursework.cs.duke.edu/help/ssh/README
The rest of these instructions are supplementing what you see in this README file
If you have not already generated an SSH key for another class:
- Within Terminal/Shell, do Step 1 in the second section "Generating a new SSH key pair" and accept the defaults (steps 2 and 3)
```
    ssh-keygen -t rsa -C "NETID@duke.edu" -b 4096
```
- Copy public part of the key using the command given in step 4 corresponding to your OS
If you have not already connected your current computer to our Gitlab site:

Within Terminal/Shell, copy the public key using the command given in Step 4 in the second section "Generating a new SSH key pair"
Within a Browser, paste the copied public key into the Gitlab text area (User Settings -> SSH Keys -> Key Text Area)
giving it the same title: id_rsa, and press Add key

Getting Your Own Copy of a Gitlab Project's Starter Code

Within a Browser, visit the project for this lab, CompSci307_2019Spring/lab_hangman
Press Fork to create a version of the project in your own account with the same name (e.g., GITLAB_ACCOUNT/lab_hangman)
Note, you will use fork to create your own repository of lab projects, but a repository will be provided for you for assignment projects (so no fork is needed)
On the new project page that appears, copy the SSH URL (e.g., git@coursework.cs.duke.edu:GITLAB_ACCOUNT/lab_hangman.git)

Cloning Your Copy of the Project onto Your Local Machine

Within Terminal, change to your workspace folder
```
    cd WORKSPACE/FOLDER
```
Download a local version of the project that is linked to your Gitlab repository (this is the URL you copied in the previous section)
```
    git clone git@coursework.cs.duke.edu:GITLAB_ACCOUNT/lab_hangman.git
```
That command should create a folder named lab_bounce within your workspace folder that contains configuration information for GIT (e.g., .git)
```
    ls -a lab_hangman
```

Importing Your Local Copy into IntelliJ

Within IntelliJ, select Import Project (or New -> Project From Existing Sources)
Select the folder you just created: lab_hangman, and press Open
For the series of dialogs that appear you can just accept the defaults by selecting Next
Run the program to verify that your it is working
1. Click on the Project label in the leftmost gutter to expand the contents of your project folder (if it does not expand automatically)
2. Right click on the folder named data and select Mark Directory As -> Resources Root
3. Click to expand the folders src to find the Java class Main
4. Right click on this class to run it by selecting Run Main.main()

If there are compilation errors or it does not run, then you may not have installed the latest versions of Java or IntelliJ or the project is not correctly configured.

Push Changes to your Project back up to Gitlab

Within Terminal, your lab_hangman folder should now have the configuration information for both GIT (e.g., .git) and IntelliJ (e.g., .idea)
```
    ls -a lab_hangman
```
Within IntelliJ, open the file README.md by double clicking on it
Add your name and save the file
When you do this, you should see the file's name in the Project View's list of files change color to indicate GIT knows it has been changed
Within Terminal, you can verify that GIT also knows that it has been changed by typing
```
    git status
```
Add your changed files to those staged for your next commit
```
    git add README.md
```
Then note that all the added files should be grouped together into a single commit to the repository, with a message describing the changes contained in this commit
```
    git commit -m "Included my name in the README"
```
Push all your commits to the remote repository, e.g., Gitlab, so that others (UTAs, teammates, etc.) can see your changes
```
    git push -u origin master
```
Within a browser, refresh the Gitlab page for your repository to see your changed README file

Practice Making Changes

Change one or more of the code files by adding or removing comments, creating multiple commits and pushes, until you feel comfortable before moving onto discussing and refactoring the code itself.

Resources

Submission

What is in your lab_hangman repository on Gitlab at the end of lab is what will be considered your submission. This is how all submissions will be done for this course — only what is in your Gitlab repository will be considered part of your classwork.