You will be using git for accessing all course material as well as for project submissions:
All course material is maintained on a git repository hosted on a CS department machine. You will be mirroring this repository on your VM.
You should access course files only via this mirror. DO NOT DOWNLOAD MATERIAL DIRECTLY FROM THE WEB SITE.
You will be submitting your course projects using a private git repository on github.com.
Project submission will be done from a clone of your github repository on your VM.
This document assumes that you have already set up your VM.
This document provides step-by-step directions for mirroring the
course repository and setting up your github repository. You can
obtain basic familiarity with git by looking at the copious
documentation and tutorials available on the web. This
presentation
is recommended.
Set up your global git identity on your VM:
$ git config --global user.name "Jane Doe" $ git config --global user.email "jdoe@binghamton.edu"
Substitute your name and email address suitably above.
On your VM, create a public-private key-pair:
$ ssh-keygen
If you accept the defaults, you will create a private key in
~/.ssh/id_rsa and the corresponding public key in
~/.ssh/id_rsa.pub. The former should be retained on
your VM whereas the latter may be distributed to machines
to which you would like to access from your VM.
Copy the public member of the above key-pair to remote.cs:
$ ssh-copy-id -i ~/.ssh/id_rsa LOGIN@remote.cs.binghamton.edu
where LOGIN is your login-id on remote.cs.
You will be prompted for your password on remote.cs.
Verify that you can now ssh from your VM to remote.cs without having
to provide your password.
Clone the course web site into your home directory:
$ cd ~
$ git clone LOGIN@remote.cs.binghamton.edu:~umrigar/git-repos/cs544.git
where LOGIN is your login-id on remote.cs. All the files
contained within the course web site should be copied into a
cs544 sub-directory.
If you need to type in your remote.cs password, you have not
set up your ssh key correctly. Please review the earlier step
to see where you may have gone wrong.
Go into the newly cloned cs544 directory. You should then see
all the course web site files.
This will ensure that scripts can find the directory.
You should never be writing into this directory.
We will also be using git for project submissions:
You will be submitting your course projects to a private git repository on github.com which you share with the grader.
Projects/labs submissions will be done from a clone of your github repository on your VM.
If you know what you are doing, this tl;dr section should largely suffice:
Set up a personal github account and create a private i444 or
i544 git repository, depending on the course you are registered
for. Choose the github options to generate a .gitignore for
node and initialize your repository with a README.
Set up the grader with github user id denyshubh to have access to
your repository.
As there are many similar names and some people may have multiple accounts, make 100% sure that you have the correct github accounts (the above ID must match).
Clone your github repository into your home directory on your VM.
Use a submit subdirectory within the cloned directory for
working on projects. If submitting late, email the grader for
that project.
The following sections explain each of the above steps in detail.
Each student needs to set up a private git repository called i444
or i544 (depending on the course you are registered for) on github.
It will be referred to as iX44 in the sequel. This repository needs
to be shared with your CS 444/544 grader and will be used for
submitting projects for grading.
Point a browser to github.com.
Click on Sign Up, and complete the form. You may choose any
appropriate Username, but it is strongly recommended that you
use the user-name associated with your binghamton.edu email (if
it is available).
Please ensure that you provide your binghamton.edu email address
in the Email address field. This may make it slightly easier
for the grader to associate your github account with your BU id.
Please complete all necessary steps to complete your registration on github after satisfying their captcha and submitting the form.
Set up your account appropriately. On the github page, access your account using the user icon on the top right of the page and selecting Settings. Select SSH and GPG keys from the left hand menu, then click New SSH key.
On a terminal in your VM cat ~/.ssh/id_rsa.pub and then
copy-and-paste the output of that command into the provided Key
box. Submit the form to set up your new key.
To set up a project for the course, click on the green New button on your github home page.
Fill in the repository name as i444 or i544, depending on
the course you are registered for (this is absolutely
essential).
Provide a suitable description for the repository.
Make sure that you set up your repository as Private.
Select Add a README file.
Specify a .gitignore file for node.
Hit the Create repository button.
Go to your repository using the link you will now find on your
github homepage. Go to Settings->Collaborators from the
left-hand side navigation. Add the grader with github user id
denyshubh as a collaborator.
As there are many similar names and some people may have multiple accounts, make 100% sure that you have the correct github accounts (the above ID must match).
This will provide the grader access to your repository once the invitation to collaborate is accepted.
Clone your github repository into your ~/projects directory:
$ cd ~
$ git clone YOUR_GITHUB_PROJECT_URL
You can copy and paste YOUR_GITHUB_PROJECT_URL from your github
project page. Click the green <> Code button and then copy the
SSH url into your clipboard by using the copy widget on the
right of the url.
If you get an error when doing so, verify that you have correctly uploaded your public ssh key to github.
If you cd over to your i?44 directory and do a ls -a you should
see both the README.md and .gitignore files. Feel free to add
names/patterns into .gitignore file for files which should be
ignored by git. For example, if you are using emacs as your text
editor, you may want to add in a line containing *~ to tell git to
ignore emacs backup files.
Make sure that all updates have been pushed over to github:
$ cd ~/i?44 $ git status -s #see if there are changes you want to commit $ git commit -a -m 'SOME COMMIT MSG' #commit if necessary $ git push #push changes to github
You should feel free to create any other subdirectories within your
i?44 directory. The only directory which will be monitored for
submitted assignments is the submit directory in the main branch.
You can set up automated updates for your cs544 course repository.
You can also manually update it and use git to track changes.
You should set up a cron job to update your ~/cs544 directory from
the course git repository:
$ EDITOR=YOUR_FAVORITE_EDITOR crontab -e
where YOUR_FAVORITE_EDITOR is the command you use to start your
preferred editor. It should open up showing you an initial crontab
file. Add the following line at the end:
BB * * * * cd ~/cs544; git pull > /dev/null
where BB is your B-number modulo 60. Ensure that you have a newline
at the end of this line. Save the file and exit your editor.
The cron job should update your repository every hour at BB minutes
past the hour (by specifying the minutes using part of your B-number,
we ensure that students do not all update at the same time, potentially
causing an overload).
You should treat this directory as a read-only directory.
If necessary, you can also manually update your ~/cs544 directory:
$ ( cd ~/cs544; git pull )
You can get a summary of all git changes by running a Ruby script:
$ cd ~/cs544 $ bin/git-changes.rb .
This will output a summary of all git changes since the last time you
ran the script (it records the time via a timestamp stored in
~/cs544/.last-login). It will not produce any output the first
time you run the script.
If you want to see all the commits in a particular directory like hw/hw1:
$ cd ~/cs544 $ git log --oneline -- hw/hw1 dcdef92 minor hw1 changes 05fc1a1 added hw1; minor correction to prj1 $
Your commit id's and messages will differ.
If you want to see the details of a particular commit, use:
$ git log --stat dcdef92^!
To see the diff's for a particular commit-id:
$ git show dcdef92
To restrict the diff's to a particular path:
$ git show dcdef92 -- hw/hw1/hw1.umt
A common git workflow is to work on new program features
in separate git branches and merge each feature branch in to the
main branch when the feature is complete. This course will expose
you to this workflow by regarding each project as a separate feature
and using a separate branch for developing each project.
The following lists generic steps necessary to work on your first project
prj1. You will need to adapt those steps for subsequent projects.
Note that what is listed here are generic instructions, if the project provides specific instructions, then those instructions override those provided here.
The git commit comments specified by the -m option are only examples;
you may replace them with more suitable comments.
Create a branch and a new directory for working on your project:
$ cd ~/i?44 #goto local clone of github
$ git checkout -b prj1 #create new branch
$ git push -u origin prj1 #push new branch to remote
$ mkdir -p submit #ensure you have a submit dir
$ cd submit #enter project dir
$ cp -r ~/cs544/projects/prj1/prj1-sol . #copy provided files
$ cd prj1-sol #change over to new project dir
Set up this project as an npm package:
npm init -y #create package.json
Commit into git:
$ git add . #add contents of directory to git
$ git commit -m 'started prj1' #commit locally
$ git push -u origin prj1 #push branch with changes
#to github
Follow the directions given in your project assignemnt to set up typescript and any necessary library packages.
If your project requires more external js modules:
$ npm install MODULE...
$ git commit -a -m 'added dependencies'
$ git push
Work on your project. You should get into the habit of committing and pushing frequently, making it easy for you to recover from unsuccessful changes or a crashed VM. Some git commands which may prove useful:
List local branches using git branch -l. The current branch
will have an asterisk next to it.
Switch the current branch to branch B using git checkout B.
Add new files, directories and changes to the git staging
area using git add.
$ git add *.mjs #add all js files in current dir
$ git add . #all all files, dirs, changes in
#current dir to git staging area
Commit changes locally.
$ git commit -m 'MSG' #commit staging area
#with message MSG
$ git commit -a -m 'MSG' #commit staging area
#and all working directory
#changes
Push all committed local changes to remote github repository
using git push.
Once your project is complete, move it over to the main branch and submit it by pushing it to github:
$ git checkout main #go to main branch
$ git status -s #should show no outstanding changes;
#otherwise add and commit till git status
#shows no outstanding changes
$ git checkout prj1 #go to project branch
$ git status -s #should show no outstanding changes;
#otherwise add and commit till git status
#shows no outstanding changes
$ git merge main #merge any changes from main.
#should not cause any conflicts
#since all and only prj1 changes are
#in this branch
$ git commit -m 'merge main' #commit
$ git push #and push changes
$ git checkout main #back to main branch
$ git merge prj1 #should be a fast-foward merge
$ git commit -m 'merge prj1 sol'
$ git push #submit project on main branch
You should use the github web interface to verify that the project has been submitted correctly to github.
If you are sufficiently paranoid (in general, you should be
paranoid when working with computers :-( ), you will verify that
it is possible to run your project using only what you submitted
to github:
$ mkdir -p ~/tmp
$ cd ~/tmp
$ git clone YOUR_GITHUB_REPO_URL
$ cd
# setup symlink at same dir level as your i?44 symlink
$ ln -s tmp/i?44 tmp-github-repo
$ cd tmp-github-repo/submit/prj1-sol
$ npm ci #build your project
You can now test your project. If everything is ok:
$ rm ~/tmp-github-repo
$ cd ~/tmp
$ rm -rf i?44 #rm cloned project
If you discover errors in your project after your initial submission, you can resubmit; the project submission time will be the time of the last submit.
Once you are happy with your project submission, you can clean up the project branch:
$ git push -d origin prj1 #rm remote branch
$ git branch -d prj1 #rm local branch
If you submit late, please email the grader.
Scott Chacon, Ben Straub, Pro Git.
Anish Athalye, Version Control (Git); Part of MIT Missing Semester; Highly recommended.