¶ About Git and Github
Git is a distributed version control system. The revisions are saved locally and the entire repository can be synced with other repositories.
To learn about Git,
man gittutorial
is a good place to start, and The Git User's Manual can give all the information needed (and there are more than a handful of other tutorials on the web).
Github is a centralized service for hosting git repositories.
¶ Github at CS - private instance
The school has its own instance of github at https://github.cs.huji.ac.il. All of the school's students and staff have an account there (using the normal unix login+password). This service is accessible world-wide, which allows to work on code at home and sync it to the cs network without the need for ftp or scp.
There are a couple of differences between the public github instance and CSE instance:
- CSE Users can have infinite private projects, while on github.com only one is allowed in the free edition.
- Projects can’t be shared as public for non cse users. Public projects will be available only to cse users.
- For collaborative work with external users (public or private), they will have to open a CS account.
¶ Initial setup
A one time procedure is needed to set up the git environment to work properly (such as setting up credential and setting the user data):
¶ Inside the cs network on linux machines
It is best to run the
github-setup
command, and follow the instructions:
<5|0>zivben@dali:~% github-setup Using existing public key for data Please go to
https://github.cs.huji.ac.il/settings/tokens
, with your CS username and password, and click "
Generate new token
" with: Note:
setup
Check:
admin:public_key
Click
"Generate token"
Once you log in to the HUJI github page, click the "generate new token" button:
Once there, recall the instructions from the command line tool and fill in "setup" as the note, and tick the "admin:public_key" box like so:
Now scroll down and click the green "generate token" button. You will be transferred back to the tokens screen, but this time your new token will appear:
Copy the token string and paste it back to the command line prompt:
<6|1>zivben@dali:~% github-setup Using existing public key for data Please go to
https://github.cs.huji.ac.il/settings/tokens
, with your CS username and password, and click "Generate new token" with: Note: setup Check: admin:public_key Click "Generate token"
And paste the token here: 41893856a42ef0db5dae9db35fd3faeb6e66a3f6
Adding key to github
~/.ssh/config already has a github.cs.huji.ac.il configuration
You can now delete the token (from http://github.cs.huji.ac.il/settings/tokens )
This will set up the local git configuration and the ssh id in the github so that a password won't be needed for each sync.
¶ From home or non linux machines
The standard github instructions should work. In addition, to have the git submit command working, the following command needs to be executed:
git config --global alias.submit "push origin master:master master:submit"
Our github currently only knows of the cs mail addresses. As such, it is important to commit using the cs.huji mail address. To set this up:
git config --global user.name "<My Name>" git config --global user.email "<login>@cs.huji.ac.il"
For efficient use with the credentials it is recommended to connect via SSH.
Other github operations can be found in the github help
¶ Github Pages
Github pages are available. See GitHub Pages for more details.
¶ Github for exercise submission
Github can be used for working on exercises for CS courses. Each exercise needs to be specifically designated as a GIT type by the course's staff for this to work.
Once an exercise has been set for git usage, a repository will be created for each student in the github in the form:
<course>-<year>/<exercise>-<login>
e.g.
intro2cs-2016/ex1-penguin7
The <year> is the year at the start of the academic year. Even for second semester courses which technically starts at the next civil year.
This repository is opened for the student for read/write (pull/push). And it is opened for the course's staff as read only (pull). If working in pairs, it will be opened for the paired student as well.
Normal submission will be disabled for git type assignments, and any attempt to submit through moodle will result in moodle taking github's last submission.
¶ For students
First make sure to set up the git environment (this is a one time procedure for all courses):
github-setup
All the examples below are using these example parameters (as above):
- course - intro2cs
- year - 2016
- exercise - ex1
- user - penguin7
Once an exercise is defined by the course, you can access it through the web
http://github.cs.huji.ac.il/intro2cs-2016/ex1-penguin7
To clone the repository and start working on it:
git clone git@github.cs.huji.ac.il:intro2cs-2016/ex1-penguin7.git
To add files to the repository (e.g. some-file.py):
git add some-file.py
After working on the exercise, to commit a well defined set of changes:
git commit -a -m "commit message"
The "commit message" should be a short (or multi-lined long) description of this commit.
To push the changes to github:
git push
This will make the changes available in github, but not considered as submitted yet
To submit the changes:
git submit
To see the local status of the git repository (local changes):
git status
To undo changes to 'afile.py' and restore from the last commit:
git checkout -- afile.py
Once the changes have been submitted, the submission will be processed and a mail will be sent once the process is completed (shouldn't be more than a few minutes, using the "bodek" system).
Important: The submission is through a special git protected branch "submit". Any advance git operations (rebase, reset --hard, merge, etc.) which might break the sync between the master branch and the submit branch, will require re-merging of them in order to work again.
¶ For teachers
If you want to use github for assignments, please contact the system in advance, as opening the github's organization for the course needs a one time manual operation (per course per semester, not per assignment).
Some general details regarding using github for submissions:
- The repositories creation and verification is resource intensive, and runs daily at night. This means that if a new assignment is opened, the repositories will be opened only the next day. The same goes for new students, the repositories will be opened one day after they appear in moodle.
- The submission is to a special protected branch "submit", this means that once something is committed to that branch, it cannot be "uncommitted" and so you can follow to some extent the student's progress.
- Due to technical reasons, each repository is started with an initial README.md file. This file is not needed and you can instruct students to delete it (or use it).
- Each push to the "submit" branch (git submit) is logged and accessible through ~<course>/course-admin/gitdle/<assignment>/pushes/<student>
- Using git will automatically use the bodek system, as this is the system that does the checkout. When submitting through git, the submitted tar file (taken out of git) will reside in the ~<course>/course-admin/ directory as usual, and it should be considered as the real submission (not the git's).
- The repositories are not locked when the deadline has reached. Students can push changes there, but they won't be submitted to moodle (and the students will be notified by mail that their submission have failed).
- There are a few additional repositories opened besides the students assignments:
- <course>-<year>/<course>-private: a general private repository for the course to use. Only the course's staff have pull/push access to it.
- <course>-<year>/<course>-public: a general public repository. The staff have push/pull and the students have pull access.
- <course>-<year>/<assignment>-<course>-private: a private repository per assignment.
- <course>-<year>/<assignment>-<course>-public: a public repository per assignment. You may use this repository to distribute some material for the students like initial files or some tests. But users can't fork it. You will have to instruct students how to initially pull the data into their repository and merge if there are changes. If this operation is required and you need help with the merging commands, please contact the system.