EGR 103/GIT2018

Introduction

Starting in the Fall of 2018, students in EGR 103 will be using a program called git in order to back up their work for EGR 103 and to put their work into a repository that is accessible to the TAs and instructors. While there is naturally some overhead associated with learning how the program works, understanding git is a valuable skill for people taking EGR 103 to have.

For EGR 103 for the Fall 2018 semester, students will be using Duke's Git server, gitlab.oit.duke.edu (referred to as Gitlab from this point on), to serve as a host for their git repository. Students will also be pulling a repository from Gitlab which contains files created during lectures and labs. The following sections go through the process of setting everything up -- please be careful while following these instructions, and if you have any questions, ask a TA or the instructor for help. For Lab 1, you will be setting up your gitlab account and creating your folder for the class. During Lab 2, you will set up your own repository to save your work and link it to your class directory.

Lab 1 Processes

Setting up your Gitlab account and SSH Keys

To set up your Gitlab account, you will need to log in to Gitlab. To do anything with it, however, you will also need to give Gitlab a piece of code - known as an SSH Key - that Gitlab can use to confirm you are who you say you are. The following will go through the process of setting up your account, generating a key, and adding that key to Gitlab.

• First, you will need to have a web browser open - it does not matter which one. Navigate to gitlab.oit.duke.edu
• Do not put your NetID or password in the boxes; instead, click on the "Duke Shibboleth Login" button.
• At the Duke Sign In page, Log in using your OIT credentials
• At top right, there should be a drop-down menu - click on the v and go to Settings.
• In the Name box, put in your name, followed by your NetID in parenthesis. For example, Dr. G's is

Michael R. Gustafson II (mrg)

Be sure to include any number that forms a part of your NetID.

• Click on the SSH Keys entry in the menu at the left of the page; of the icons that look like keys, it is the first one and the smaller one.

<-- -->

• The browser should now be waiting for you to add an SSH key.

Now you will need to generate a key and copy it into this space. To do that, you will need to log in to the Duke Unix machines and then issue Unix commands to have it create a key for you. The following commands will all be in a terminal window:

• Open MobaXterm and, if need be, start a local terminal
• At the prompt, type

ssh -XY NetID@login-teer.oit.duke.edu

where NetID is your NetID

• When prompted, type your password; note that the cursor will not move as you type
• To create an SSH Key, type:

ssh-keygen -t rsa -C "NetID@duke.edu" -b 4096

where, again, NetID is your NetID.

• Accept the default location, which should be /winhomes/NetID/.ssh/id_rsa
• Hit return twice to skip over generating a password
• Now, to see the SSH Key, type:

cat ~/.ssh/id_rsa.pub

• To copy the SSH Key to your clipboard, simply select the text starting from ssh-rsa and ending with NetID@machine or NetID@duke.edu

You will now paste this key into the Key section of the "Add an SSH Key" web page in your browser. You can leave the title as the default case or give it a different name if you wish. Then click the Add Key button:

From this point forward, when any of the OIT Linux machines interact with your Gitlab account, the keys will be used to verify that you are who you say you are.

Setting up your EGR103 Folder

Next, you will set up the folder where you will be saving all your work. To do this:

• First go to your home directory:

cd ~

• Now create a folder called EGR103:

mkdir EGR103

• Change into that folder:

cd EGR103

• Create a folder for the first lab called lab1:

mkdir lab1

• Change into that folder:

cd lab1

Lab 2 Processes

Now that you already have your Gitlab account and your connection for public lab files set up, this week you will be adding a connection to a folder containing any files discussed during class and lab. As with the EGR103public folder you made above, you should not make any changes to the files inside this folder; rather, you should pull the files from the repository and then make your own copies if you could like to make any changes.

Getting the lectures repository

Now you will be cloning a repository that contains some of the files that you saw on Monday. From here on out, all you will have to do is update your local copy of this folder to get anything else that was posted during class or lab. For this week, you will need to create a space for the files then tell git where to get the necessary information. All of the commands below will be on the command line in your terminal (MobaXterm) window:

• Go to your home directory:

cd ~

• Tell git to clone a preexisting repository - this will automatically create a folder with the name of the repository and will put the files in it:

git clone git@gitlab.oit.duke.edu:mrg_public/EGR103F18lectures.git

• Change the name of the folder to be a little shorter

mv EGR103F15lectures EGR103lectures

You should only ever need to issue the clone and mv commands for this folder once. From this point forward, if you want to get the most up-to-date version of the lectures repository, all you have to do is change into the EGR103lectures directory and pull the files:

cd ~/EGR103lectures
git pull

To make sure your folder is correctly connected to the repository, you can look at your configuration file. Make sure you are in the EGR103public folder and then type

more .git/config

The output should closely resemble:

[core]
        repositoryformatversion = 0
        filemode = false
        bare = false
        logallrefupdates = true
        ignorecase = true
[remote "origin"]
        url = git@gitlab.oit.duke.edu:mrg_public/EGR103F18lectures.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
        remote = origin
        merge = refs/heads/master

Lab 3 Processes

During this lab, you will set up your own gitlab repository, link your directory to it, and push your files to the repository. From this lab forward, you will need to push your EGR103 folder every time you have finished making edits to your files.

Creating your class repository

For the next step, you will be working in the browser with the Gitlab page again. You will be creating a Group - which is the top-level organizational structure for Gitlab - and within that you will be creating a Project. The project will be where all your files for the class are backed up. You will be granting access to the instructors and the TAs to view the project for this class -- that will help us help you if need be and will also make it possible for us to grade some of your work online. Please carefully follow the process below:

• If you don't already have a browser open and pointing at Gitlab, open a browser, navigate to gitlab.oit.duke.edu and log in using the Shibboleth button.
• Click the Dashboard icon at the top left:
• If there is a tabbed window at right, select the “Groups” tab then click the “New group” button under the tab; if there is not a tabbed window at right, click the New Group button in the dashboard.
• In group path, using YOUR NetID, put in NetID_classes - be sure to include the underscore character.
• In the details block, write a note to yourself that this is the group where class pages go
• Click the Create Group button - this should create the group and then go to the group’s page:
• Click the New project button on the right:
• In the Project path, type EGR103
• Make sure the Visibility Level is Private:
• Click the Create project button:
• Click on Settings at left:
• Click on Members, located directly under settings; the icon looks like a group of people:
• For the next part, you will be adding the instructors and your lab section TAs; their NetIDs will be written on the boards at the front of the room.
  • Click on the New project member button at right:
  • In the people box, add mrg
  • In the Project Access drop down, change to Master:
  • Click the Add users button
  • Repeat these four steps for the four TAs and for the Head TA

Pushing your class directory

Finally, you can go back to your Unix account to link and push your folder. Go back into your terminal window and perform the following steps:

• Change into your home folder

cd ~

• Change into your EGR103 folder

cd EGR103

• Make your EGR103 folder a repository

git init

• Add all the folders inside your EGR103 folder to the first set of items to push to the repository

git add .

• Commit all the items you just added to push to the repository

git commit -a -m "First Commit"

• Connect your folder to your repository - be sure to replace NetID below with *your* NetID:

git remote add origin git@gitlab.oit.duke.edu:NetID_classes/EGR103.git 

• Push your files to the repository

git push -u origin master

Of the commands above, you should only have to issue the init and remote commands once. From this point forward, you should be able to send your most updated version of your files to the repository by going into your EGR103 directory and then typing

git add .
git commit -a -m 'Message'
git push

Note in the latter case that you do not have to append the -u origin master part after the first push. If, for some reason, you need to retrieve an archive copy of your files, you can do this by going into your EGR103 directory and then typing

git pull

However, you will typically not need the git pull piece as the files on Unix will generally be the most updated. If you lost files, or edited them in a way that you need to recover an older version, git pull will be able to help you there.

Week 6 Processes

For Week 6, you will be changing your initialization scripts in order to have some shortcuts for LaTeX and for git. The files are on Sakai and are described on BASH_Shortcuts. The following is how to get the shortcuts to work on your account:

• Log in to login-teer.oit.duke.edu and stay in your home directory
• Type

ls .bash*

and hit return. There should not be a .bashrc or .bash_profile file as yet; if there is, not not continue. Ask Dr. G about this in lab.

• If those files are not there, continue by starting a browser with

firefox &

• Log in to Sakai with that browser, go to the EGR 103 site, and click on the Resources link at left
• Click on the Bash Files folder
• Right-click the .bash_profile file and select "Save link as..." In the window that comes up, at the top, type

/winhomes/NetID/bash_profile

and then save the file there.

• In the terminal window, you will now need to rename this file. Make sure you are still in your home directory and then type

mv bash_profile .bash_profile

The only difference between the two is the latter has a dot in front of it.

• Go back to the firefox window from Unix, right-click the .bashrc file and select "Save link as..." In the window that comes up, at the top, type

/winhomes/NetID/bashrc

and then save the file there.

• In the terminal window, you will now need to rename this file. Make sure you are still in your home directory and then type

mv bashrc .bashrc

The only difference between the two is the latter has a dot in front of it.

• You can now log out and log back in. When you do, the ltx and gitpush103 short cuts described at BASH_Shortcuts will be available.

General Practices

Whenever you first log in to do work for a new lab, you will want to make sure to get the most updated version of the public files; that process will be in the terminal window:

cd ~/EGR103public
git pull

You will then want to set up a folder for that lab in your own EGR103 folder and put your work there:

cd ~/EGR103
mkdir labNN
cd labNN

Finally, whenever you are finished working or if you just want to make sure to push any changes up to the repository, you will want to push your entire EGR103 folder up to the Gitlab server:

cd ~/EGR103
git add .
git commit -a -m 'Message'
git push

You must be sure to use the add, commit, and push commands before you log off the system. Not only will that back up your work but it will also put the files in a location where the instructors and TAs can see them to potentially help with coding issues you may be having. Also, sometimes your files will be needed for grading purposes - having the latest and greatest in your repository will make it possible to give you credit for your work.

Troubleshooting

fatal: Not a git repository (or any of the parent directories): .git

If you get this error, you are not in a folder that is connected to a repository. Type pwd to see where you are - it is probably either your home directory or, if prior to week 3, your EGR103 directory.

error: Your local changes to 'file' would be overwritten by merge.

If this happens, ask Dr. G about it during lab. "Fixing" this incorrectly can cause you to lose a great deal of work...