CTH-2016 / Assignments Configuration

What follows is a recipe to initialise a git repository for your class assignments.

Step 1: Create repository on Github

First create a repository under your github account. To do so, login to Github and on the top/right corner of the page select the '+' symbol and 'New repository'

* Note 1: Select "Initialize this repository with a README" * Note 2: From the "Add .gitignore" drop down menu, selecte Node

Step 2.0: Clone the repository to your own machine using git

Now that you have a github repo, you need to clone it to your machine. Open a terminal and navigate (cd and ls) to a prefered directory on your machine where you want your assignments to reside (for instance the Desktop).

When this is done, select the "Clone or download" menu on your githib repo's page and copy the listed url:

Coming back to your terminal, simply type the following to clone the repo on your machine:

This will create a directory under the current folder where your terminal is. To view the changes, simply type:

(Alternative) Step 2.1: Clone the repository to your own machine using Github Desktop

This is an alternative to Step 2.0: Clone the repository to your own machine using git

Now to clone your repository (created on Step 1), select "Clone or download" menu on your githib repo's page and click on the "Open in Desktop":

This will open Gihub Desktop and ask where you what to clone your Gihub repository on your machine.

Creating a new assignment (Node + Git)

What follows is a recipe to create a new assignment in your newly initialised git assignments repository.

Step 1: Create a new directory under your assignments repository

If you have followed the previous section, you should now have a repositroy on your machine which is linked to your github account. Let's assume that your repo is named cth2016-assignments/ and resides on your Desktop.

and then create a new directory, which I will call assignment-x. To do so, on the terminal, simply type:

This will create a new direcory assignment-x under ~/Desktop/cth2016-assignments/. The cd command puts your terminal inside this newly created directory so that you can initialise your actual project in step 2.

Step 2: Initialise you project with npm init

Node has a package manager named npm (n-ode, p-ackage, m-anager) that automates the task of creating a project from scratch and configures it in a way that is compatible with other node projects. We will use npm during the module.

To initialise your new assignment under assignment-x, simply emit the follow command:

With this commad you will be asked various questions regarding your project's name, version, description, entry point, author, etc. which you can configure at will (press <'enter'> to select and move to the next configuration step).

A package.json file is created upon the completion of npm init. This file contains all the configurations you selected and can be edited manually.

Step 3 (optional): npm install --save commander

This step is optional, yet recommended for your assignment. When making a node application, modules/libraries can be made part of your project using npm. Thousands of javascript libraries are available on www.npmjs.com which you can install with a simple npm command.

As in the first session of the class on the Command Line Interface (CLI), we will be using "commander" for our applications. To install it for you assignment, use the following command:

This will create a node_modules directory next to package.json where the commander code is placed. All modules installed using npm will reside in this node_modules directory.

Step 4: Create your actual assigment script(s)

Now that you have an npm project created and installed commander it is time to create your script(s). For instance, in this example, I will create index.js file containing the code for the fake assignment. This file can be called anything (for instance, person.js as in the example in class during week1).

Though since I am not following a proper assignment per se, I will simply create a simple tri-lingual script that will output "Hello!", "Dag!" or "Allô!" depending on a command line arguments passed to the script which can be of the type en (english), nl (nederlands), fr (français) or nothing.

To create index.js simply type (or, alternatively, create it with Sublime Text):

Now open the file usign Sublime Text, copy/paste or input the desired code and save:


// simplest tri-lingual program 

var program = require('commander');
 
program
  .version('0.1')
  .option('-l, --language [code]', 'Language', /^(en|nl|fr)$/i)
  .parse(process.argv);

switch(program.language)
{
    case('en'):
        console.log('Hello!');
        break;
    case('nl'):
        console.log('Dag!');
        break;
    case('fr'):
        console.log('Allô!');
        break;
    default:
        console.log('...');
        break;
}

Step 5: Run you script

If you called you script another name (for instance, person.js), please change the above index.js with the name of your own script.

Step 6: Create a README

One of the interesting feature of commander is that it can auto generate a "help" output from your script based on the command line options you have listed in your program.

It is very common for command line scripts to feature such --help argument that when executed, displays what the program expects as input. Thus, for this class, each README you will create (for both assignments and final project) is expected to have (at least) this type of "helper documentation".

Alternatively, you can create the README with Sublime Text and copy/paste the result of the --help manually.

It is a very good practice to start the redaction with the --help as it signals how to use your script to people that may be interested in it.

Step 7: Add your created files to git

Now that you have a proper project initialised, the next step is to add all its files to git.

If you have followed the previous steps, git status should simply signal that the current directory ./ is untracked. To add it to git:

and check that your package.json, index.js (or whatever you have called your file(s)), and README are marked as new files (green).

Step 8: Commit your changes and push to Github

You should now see these changes online in your new cth2016-assignments/assignment-x/ directory:

NOTE: node_modules is not be pushed to github, why? Because when someone will clone your project (your instructor for example), she/he will npm install it her/himself as it is listed as a dependency in package.json.

(Alternative) Steps 7-8: Add, Commit and Synchronise your work with Github Desktop

When you have cloned your repository using Github Desktop, you can synchronize the changes you have made in Steps 1 to 6 using the Github desktop interface:

First, commit your changes with the "Commit button" then synchronize your changes using the "Sync" button.

Updating your assignment as you make progress

It is assumed that you will make many changes to your assigment while your a working on it.

The ususall cycle of working on some piece of code is to first (1) add you files to the repo (re: Step 7), (2) modify your files while you are working, and (3) when your code is working as inteted, commit your changes and push to github (re: Step 8).

(Alternative) Updating your assignment as you make progress using Github Desktop

When you have cloned your repository using Github Desktop, you can synchronize the changes you are making using the Github desktop interface: