Git and Markdown

Lab 2: Git and Markdown

This lab is a continuation of the tutorials from Lab1. You will be creating a git repository (repo) on the Pomona gitLab server and learning how to work with this repository in vscode. Finally, you will learn how to work with markdown files – a human readable file format that is used extensively in software development and which you will be using for laboratory reports.

1. Overview

Deliverables

  1. The creation of your private repo in the csci181u-iot group.
  2. An example markdown file “example.md” demonstrating various aspects of markdown
  3. A lab report, “report.md”, in markdown format. This report should
    • Describe (briefly) what you did in this lab
    • Report on any issues that arose

I am not expecting verbose project reports; however, they should be complete at a high level and clearly written. In future labs your project report will explain any code that your write and these, rather than the code itself, will be the primary vehicle for grading the lab.

The lab report is discussed at the end of this document. You may want to collect screen shots along the way that you can add to your report.

The grading rubric for this lab is

  • Completion of tasks 60%
    • I will check for your repository and make sure that the required files are there
  • Lab report 30%
    • Overview explaining what was done: 15 pts
    • Issues that arose: 15 pts
  • Amusing example markdown file 10%
    • Coverage of markdown features 8 pts
    • Inclusion of an image 2 pts

I have to look at all these, so make me laugh. Keep in mind I’m totally out of touch with cultural references for your generation – so out of date that my daughters find it funny.

Version Control with git

All the code and reports that you develop for this class will kept be in a git version control repository (repo) to which only you and I have access. My access is to enable me to grade and provide feedback on your work. As I discuss below, while your repo will reside on the Pomona College gitLab server, you will perform your work on a working copy of your repo kept on your workstation and periodically synchronize the state of the server copy and its working copy (s). In addition, everybody in the class will have access to a repo containing templates and other course materials that I will maintain.

In the following I use master to refer to the server-based copy of your repo and clone to refer to a working copy kept on your workstation. This is not standard terminology and is somewhat in conflict the with use of master to refer to a specific branch of a repository. However, in this lab we will not discuss branches and hence there should be no ambiguity.

Version control systems such as git are fundamental tools in software development that enable large teams to simultaneously work on a code base without unnecessary collisions. Version control systems provide a history of all the changes that occur to the code in a project, the means to compare various versions of any file, the ability to recover or roll-back to earlier versions of file, the ability to maintain parallel development branches, and mechanisms for merging changes in code. While these are the essential features – there are many others that provide support for complex projects that we will not be using in this class.

Code for a project is organized in a repository (repo) (gitLab calls these projects) which is organized as a directory tree with the files you create plus a set of hidden files that maintain the history of your code. For git, these hidden files are contained in a directory named .git in the root of your repo. As you make changes to your files, you will commit them to the repo at important points. Committing a file ensures that you can subsequently access the committed version.

While it is feasible to create and maintain a repository exclusively in the file system of your computer, this would miss one of the great advantages of maintaining your code in a version control system – the ability to share your code and work with others. In order to enable this sharing, we create our repositories on a server (gitLab in this class, but there are many others) and keep working copies (clones) of our repository to work on locally.

When you clone a repository, the clone contains all of the files and all of of the history of the master from which it is cloned. We can work on the code in a cloned repository even if the server is not available. This includes modifying files, committing them into the repository so that we have a persistent history, and accessing file history. Of course, as we do this, the clone and its master will diverge; to bring them back in sync it is necessary to push our changes to the server periodically. When working alone, the time between pushes might be relatively long, but when working jointly on a project it is important not to allow the clone to diverge too much. Obviously if a partner pushes changes to the master that conflict with changes you have made, problems can arise, which may require you to make decisions about how to merge the changes. Fortunately, this isn’t an issue you are likely to face in this class. To update your clone with the current code on the server you pull them into the repo.

I generally recommend to students that they commit often. This is particularly true when you about to undertake any major restructuring. I also recommend that when you commit, you annotate your commitment with a meaningful comment so you can readily find the changed files. For really big changes, it is common practice to add a “tag” which makes it easy to find the change point.
A note – I keep virtually all my work in various repos. I have repos for papers, repos for proposals, repos for code, and repos for class materials. In addition to providing access to prior changes and guaranteeing that my work is backed up, this enables me to work on a variety of computers – my office computer, home computer, laptop – without having to worry about things diverging. When I sit down to work on a repo on one of my various computers, I pull any changes from the master, do my work, and at the end commit and push my changes back to the master.

2. Creating a “throwaway” repo

In this section, you will create a throwaway repo on the Pomona GitLab server. You will clone this repository, modify a file, commit these changes to the cloned repo, and push them back to the server. Some of this work will be done at the command line and some on the server. The purpose of this exercise is to become familiar with some of the terminology of git – seeing is believing. Subsequently, most of your work will be performed within vscode which greatly simplifies the process of working with code in an existing repo. The basic steps you will follow are:

  1. log into the Pomona gitLab server – https://pom-itb-gitlab01.campus.pomona.edu/
    • If you haven’t previously, add an ssh key
    • Create a repository
  2. On your computer
    • Clone the repository
    • Make and commit some changes
    • Push your commits to the master
  3. Modify a file on the server
  4. Pull this change into your clone
  5. Check your work and delete the repo

If you have never previously used git in the current account, you should configure git by executing the following commands in a terminal window.

$ git config --global user.name "Your Name"
$ git config --global user.email "you@host"

You can see the current configuration by executing:

$ git config --list

If you do this from within a repo, you’ll see all of the configuration relating to the repo. If you do this in a directory that is not part of a repo, you’ll simply see the global information. For example or

user.email=geobrown@indiana.edu
user.name=Geoffrey Brown

Logging in

For most students, your campus single sign-on should work. Pitzer students may have to manually create an account.

Creating ssh keys

gitLab depends upon ssh keys to maintain security. You can add multiple keys (e.g. if you work from multiple computers and don’t want to use a single private key). You may already have an ssh key – check in your home directory on the lab computers /Users/your_user_name/.ssh/ for a file named id_rsa.pub. If don’t have such a key, follow the directions here:

https://pom-itb-gitlab01.campus.pomona.edu/help/ssh/README#generating-a-new-ssh-key-pair

Once you have a key, add it to your account https://pom-itb-gitlab01.campus.pomona.edu/profile/keys – you’ll need to be logged in.

Creating a throw away repo

Within the gitLab window, select the projects menu item. This will list all your current projects. Now select New Project (upper right). Type in a name like test repo, add a description, and check the initialize Readme box

This should bring you to a directory view of your project, which has only one file.

Cloning your repo

From the clone menu select clone with ssh (use the clipboard icon to add the string to your clipboard)

Now in a terminal window, change directories to someplace safe – I have a directory /Users/geobrown/tmp where I know things are going into the trash shortly. Type git clone and paste in the string from gitlab – in my case it looks like this:

$ git clone git@pom-itb-gitlab01.campus.pomona.edu:gmba2019/test-repo.git

Now cd into that directory and execute:

$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Modifying your clone

Edit the README.md file – it doesn’t matter what you put in there. I did the following:

$ echo "Test Line" >> README.md 
$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

Committing your changes

Now you need to commit your changes. This is a two step process – first you have to add the files we want to commit – either because they have been modified, or because they are new. And then you have to commit them.

$ git add README.md 
$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	modified:   README.md
Note you can also delete files (this will still preserve their committed history) – this happens when restructuring code.

Once you have added (or deleted) any files for this commit point, you must commit your changes.

$ git commit -m "Some meaningful message to yourself"
[master b2f2d20] Some meaningful message to yourself
 1 file changed, 1 insertion(+), 1 deletion(-)

$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

Notice that your cloned repo (“your branch”) is ahead of the master (‘origin/master’). It is not necessary to do anything at this stage – if you are working hard on a project, it is good to commit frequently. Once you’ve reached a good stopping point, then you should “push” your commits to the master.

$ git push
Counting objects: 3, done.
Writing objects: 100% (3/3), 298 bytes | 298.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To pom-itb-gitlab01.campus.pomona.edu:gmba2019/test-repo.git
   9442896..b2f2d20  master -> master

$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Now if you return to the gitLab window for your repo (and refresh the window) you should be able to see your changes.

Recapitulation

  • You created a repository on gitLab
  • You cloned the repository on your machine
  • You edited one or more files in your cloned repo
  • You added your changes
  • You committed your changes
  • You pushed your changes.

Making changes in the master

One last thing. Sometimes your master is ahead of your branch – for example a partner has pushed changes or you have pushed changes from a different machine. In order to bring your cloned repo up to date, you’ll need to pull the changes.

In the gitLab repo, edit your README.md – it doesn’t matter what changes you make.

  • Select “README.md” from the file list
  • Click on “edit”
  • Add some text
  • “Commit changes” – there’s a green button

Now in your terminal execute:

$ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From pom-itb-gitlab01.campus.pomona.edu:gmba2019/test-repo
   b2f2d20..189a80c  master     -> origin/master
Updating b2f2d20..189a80c
Fast-forward
 README.md | 2 ++
 1 file changed, 2 insertions(+)

This will pull the changes you made into your cloned repo. You should look to see that the changes from the web interface are now in your cloned-repo.

Delete the throwaway repo

Now you can delete this repo (project)

  1. Gitlab Home Page.
  2. Select your projects button under Projects Menus.
  3. Click your desired project.
  4. Select Settings (from left sidebar)
  5. Click Advanced settings.
  6. Click Remove Project.
You’ll have to deal with some dire warnings about the project not being recoverable. If that bothers you, don’t bother until you’re more comfortable with gitLab.
You will not need to use the command line frequently to manage your project – vscode provides a very nice interface that automates many common git tasks.

3. Creating your class repo

For this class, every student will maintain a csci181u-iot repository with their work. To make this accessible to me, this repository is created by forking a template. Professor Joseph Osborn has created some scripts to make sure that this is created in the correct way. To create your class repo, you should visit the following URL:

https://pom-itb-grade01.campus.pomona.edu:5000/fork/csci181u-iot

This URL will trigger the fork process and create your repo. Assuming all goes well, you should be able to explore this repo in your gitLab web interface. Notice that there are several pre-configured directories.

Clone your class repo

After creating your class repo (described above) you will need to clone it onto your working machine as you did for the “throwaway” repo. One of the directories, lab-instructions, in your repo is a submodule that is linked a public repo that I will maintain. This repo will include various files that you will need to complete the lab assignments for this course.

Once you have cloned your new repo onto your workstation, you will need to initialize the submodule

$ git submodule init
$ git submodule update

Because this is the first time that this course is being taught, the contents of lab-instructions will be changing over the course of the semester. Before starting a new lab, you must make sure the lab-instructions sub-module is up to date.

$ cd lab-instructions/
$ git checkout master
$ git pull
Already up to date.
$ cd ..

Later you will need to add ‘lab-instructions’ to the files that you commit.

One of the directories in lab-instructions is a template for the remainder of this lab assignment – most assignments will have such a template. Copy the template for this assignment into your repo. The following assumes the current directory in which you are executing the terminal command is the root directory of your repo.

$ cp -r lab-instructions/labs/lab2 labs/lab2

You will need to repeat these steps for every lab. Be careful to use the correct template directory !

4. Working in your repo with vscode

You will be using vscode to create and edit files for each lab.
Change directories to labs/lab2 in your repo and within that directory execute:

$ code .

It’s important that you open code in the lab2 directory – each lab has its own vscode workspace defined by the files in labx/.vscode – this is described below.

At this point you have created (copied) a number of files within your repo – in order for those files to be accessible to the instructor, you will need to “check” them in and the push the changes to gitLab. We discuss this further in below. You should use the

You can see the changes that you have made thus far in vscode by selecting the version control icon (far left) as illustrated here:

Notice that on the left two files are listed under changes – README.md and settings.json. The directories you created do not appear – only files are listed.

One confusing aspect of vscode is the use of json files to keep workspace specific settings – for example in this lab there are settings to enable pasting of figures into “markdown files”. In general, you can modify the settings of vscode either globally (user level) or locally (workspace level). Each lab template will include a directory named .vscode and one or more “.json” files within that directory.

For this lab, .vscode contains a settings file that will enable you to paste images from your clipboard into a markdown file by executing (⌘+Alt+V). This will paste the markdown image link code in your file and create a “.png” file in a directory called img. (first you’ll need to install an extension in vscode ad described below).

Choose the extensions marketplace (icon on the left side of the window) and add the “Paste Image” extension:

Creating a report.md file

Using the vscode file menu, create a new file in your labs/lab2 directory called report.md

  • In the editor window for that file, type
# Lab 2
In this lab I ...

  • Save the file

  • Select the version control icon on the left (with the ‘1’ in this image)

  • Check the ‘+’ icon that appears when you hover over the file name in “Changes”. You’ll notice that the file moves to staged changes from changes. This means it is ready to be committed to your repo. You’ll also need to check README.md and settings.json which you created by copying the template.
  • Now type a message in the message window (e.g. Creating Lab 2 report file) and execute ✓ to commit your changes.
  • Finally, ‘push’ your updates to the gitlab server by selecting push from the ... icon in version control.
Before proceeding you should read the vscode introduction to version control in vscode https://code.visualstudio.com/docs/editor/versioncontrol .

5 Markdown

In this section you will create a test markdown file. You will be following a basic tutorial (from the web), but the content will be yours. You should perform all your work within vscode !

Start by creating a file “example.md” in your lab2 directory and adding a header:

# My Example File

Now, you can examine a preview of your file by clicking the second of these icons:

This preview will track your changes – as you modify your markdown, the preview will update automatically. Markdown support is built into vscode

https://code.visualstudio.com/docs/languages/markdown

There are additional extensions available, but other than the image paste extension you installed previously, you don’t need any.

As described under Resources below, markdown is not defined by a single specification. For this portion of the lab, you should use the original markdown spec https://daringfireball.net/projects/markdown/syntax, which is a subset of all others.

Your assignment is to write an example that demonstrates all of the ideas under

  • block elements
  • span elements

The file should “make sense”, but it can be totally whimsical. I do want you include at least one image (feel free to copy something, or make a screen shot). If you’re not experienced with “grabbing” windows or sections of windows on the mac, here are some directions –

https://www.itg.ias.edu/content/keyboard-shortcuts-capture-screen-shot-mac-os-x

Put your images in lab2/img. In your md file, the reference will be something like

![alternative text](img/image_file.png)

6. Wrapping Up

Complete your lab report in report.md – you may wish to include screenshots where appropriate. Once you have finished the tasks in this lab and your report, make sure to check all the files in and push your changes. I will be using the push time to check whether your assignments in class are completed on time. Also, I can only grade work I can see and I will only be able to see the files you have pushed.

Resources

Git: The resources section (under About) lists additional reference materials on git. The “cheat sheet” is especially helpful.

Markdown One unfortunate aspect of markdown is there are many non-standard extensions. For this class you should confine yourself to those supported by gitLab since I and you will be reading these files on the the gitLab server.

https://docs.gitlab.com/ee/user/markdown.html

The gitLab markdown is itself an extension of the “common mark” spec –

https://spec.commonmark.org/0.29/

If you’re wondering how markdown is translated into html, this is a good place to look.