UNB/ CS/ David Bremner/ teaching/ cs2613/ labs/ CS2613 Lab 1

Background Reading

For every lab there will be some related reading. I'll point these out as we go through the lab, but I'll also collect them at the start of the lab in case you want to get a head start (or refer back to them later).

Part 0: Administrivia

Time
15 minutes
Activity
Reading, Q&A
  1. Take 5 minutes to skim the Course Syllabus. You're not expected to read all of the details now, but you are responsible for reading them all after the lab.

  2. What's similar to other CS courses you've taken?

  3. What's different?

  4. Key point, how are marks assigned for the lab we're just starting?

Part 1: Hello Computer

Time
15 minutes
Activity
Small groups, brainstorming
Summary
Linux command line review. VM. Text editors
  1. Split into groups of 2-4 people.

  2. Introduce yourselves.

  3. One person should "drive" the computer initially

  4. Start the VM

  5. In the VM, start a terminal

  6. Make a directory *

  7. Create a file in that directory using one of the available text editor

  8. Now clean up, removing the file and the directory.

  9. If you finish early, start again with a different driver and a different text editor.

Part 2: Frog Tutorial

Time
20 minutes
Activity
Individual work
Summary
Getting started with frog

We'll be using frog frog to keep a journal of what we learn in this course.

  1. Make a directory under fcshome that will keep all of your work for cs2613. For the rest of this lab we'll assume that directory is ~/fcshome/cs2613 (viewed from fcs-cs2613-dev or ~/cs2613, viewed from your normal FCS Linux account.

  2. Follow the frog quick start to create a frog project in a directory ~/fcshome/cs2613/frog.

  3. Start a new blog page for today's lab, and delete the fake entry created by the frog setup command.

  4. If you have extra time

Part 3: Git Tutoral part 0: Background

Time
10 minutes
Activity
Reading, Discussion
  1. Take 5 minutes and read - Section 1.3 from Pro Git. Don't worry if you don't get every detail now; you can always go back and re-read it later.

  2. What are the two most important concepts discussed in this reading?

Part 4: Git Tutorial I: Setting up a repo

Time
25 minutes
Activity
Individual work
Summary
This is where we create the git repository used for the rest of the term to hand things in.
Notes
Many revision control systems provide an add command that tells the system to start tracking changes to a new file. Git’s add command does something simpler and more powerful: git add is used both for new and newly modified files, and in both cases it takes a snapshot of the given files and stages that content in the index, ready for inclusion in the next commit.
  1. Read the git-quickref page, and follow the initial configuration steps there.

    • note that the "--wait" option for code-oss is important here.
    • One important technical detail is that there is a link from .gitconfig in the fcs-cs2613-dev home directory to your regular FCS linux home directory, so your git configuration is shared between those two environments.
  2. Change to ~/fcshome/cs2613. This directory should have one subdirectory called frog, which has the results of your experiments above with frog.

  3. Create the git repository

     $ git init
    

    Git will reply

     Initialized empty Git repository in /media/sf_FCS-HomeDir/.git/
    

    You’ve now initialized the working directory — you may notice a new directory created, named ".git". The path starting with /media has to do with with way that VirtualBox shared folders work.

  4. Next, tell Git to take a snapshot of the contents of all files under the frog, with git add:

    $ git add frog
    

    This snapshot is now stored in a temporary staging area which Git calls the "index". You can permanently store the contents of the index in the repository with git commit:

    $ git commit
    

    This will open and editor and prompt you for a commit message. Enter one and exit the editor. You’ve now stored the first version of your project in Git. See §5.2 of Pro Git for some hints about writing good commit messages. As mentioned in the class git policy, you will be marked on your commit messages, so you may as well get started with good habits.

Making changes

Having at look at our test post, we can observe the post template adds a bunch of stuff related to social media. Let's suppose that our cs2613 journal we want a more minimal look.

Start by finding the right files to edit with

$ git grep disqus

git grep is a very useful (and fast!) tool to find occurrences of strings in your git repository. Notice in the output there are some files created by frog; we will clean those up later. Find the template file (under _src) and edit it to remove the undesired social media links. Check the results with

$ raco frog -bp

Use git add to stage your changes:

$ git add file1 file2 file3

You are now ready to commit. You can see what is about to be committed using git diff with the --cached option:

$ git diff --cached

(Without --cached, git diff will show you any changes that you’ve made but not yet added to the index.) You can also get a brief summary of the situation with git status:

$ git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   file1
#       modified:   file2
#       modified:   file3
#

It’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git.

If you need to make any further adjustments, do so now, and then add any newly modified content to the index. Finally, commit your changes with:

$ git commit

This will again prompt you for a message describing the change, and then record a new version of the project.

Alternatively, instead of running git add beforehand, you can use

$ git commit -a

which will automatically notice any modified (but not new) files, add them to the index, and commit, all in one step. Keep in mind that you will be marked on the logical structure of your git commits, so you are better off using git add to explicitely choose what changes to commit.

Cleaning up generated files

Note

If you are pressed for time, you can skip to Pushing, and return to this part on your own.

A common phenomenon in software development is the existence of generated files. These files are created by some tool, typically based on some source files. In general it is a bad idea to track generated files in version control because they introduce spurious changes into history. We'll look at this more later, but for now let's try to clean up. We can find out what files are generated .e.g. by consulting the frog docs. Let's first try a shortcut. Run

$ cd ~/fcshome/cs2613/frog
$ raco frog --clean

To find out what changed, run

$ git diff --stat

All going well, you will see a bunch of deletions. We can tell git to make those deletions permanent in several ways. It turns out that there is a handy option to git add that tells git to stage all of the changes in the working tree. Try to figure out which option it is.

When you are satisfied with the changes, run git commit.

It will turn out that this is not all of the generated files; we can use git rm to clean up further as we find more.

Make sure you run

$ raco frog -bp

To make sure the the blog still works after your deletions.

Pushing to a central repo

This is the last section of today's lab that you absolutely have to understand before continuing in the course, since all marks in the course will be based on work pushed to the coursegit repos.

Since we are using the FCS git repositories there is an existing repository for all students who registered early enough. If it turns out there is no repository for you, you may have to talk to Sean Seeley.

Next steps

We'll pick next time with some discussion of using git on multiple computers, but you should have the bare minimum to hand in your work at this point.