Description
Aims
This assignment aims to give you
practice in Perl programming generally
introduce you to git & give you a clear concrete understanding of it basic semantics
Note: the material in the lecture notes will not be sufficient by itself to allow you to complete
this assignment. You may need to search on-line documentation for Perl, git etc. Being able to
search documentation efficiently for the information you need is a very useful skill for any kind of
computing work.
Introduction
Your task in this assignment is to write a Perl program legit.pl which implements a subset of the
version control system Git
Git is a very complex program which has many individual commands.
You will implement only a
few of the most importnat commands.
You will be given a number of simplifying assumptions which make your task easier.
Reference implementation
Many aspects of this assignment are not fully specified in this document.
Instead you must match the behaviour of a reference implementation –
/home/cs2041/bin/legit.
Provision of a reference implementation is a common method to provide an operational
specification, and it something you will likely need to do after you leave UNSW.
Discovering & matching the reference implementation’s behaviour is deliberately part of the
assignment.
Your Perl script legit.pl should match the behaviour of /home/cs2041/bin/legit exactly,
including for example proiducing the same error messages.
The reference implementation is a wrapper around git, so tutorials for the equivalent git
commands will help you understand the reference implementation. For example this Meet Git
video from Atlassian:
While the code in the reference implementation is fairly straight forward, reverse-engineering its
behaviour is obviously not so simple and it’s a nice example of how coming to grips with the
precise semantics of an apparently obvious task can still be challenging.
If you discover what you believe to be a bug in the reference implementation, report it in the
class forum. Andrew may be fix the bug or indicate that you do not need to match the reference
implementation’s behaviour in this case.
Legit Commands – Subset 0
legit.pl init
The init command creates an empty Legit repository.
legit.pl should create a directory named .legit which it will use to store the repository.
It should produce an error message if this directory already exists. You should match this and
other error messages exactly. For example:
$ ls -l .legit
ls: cannot access .legit: No such file or directory
$ ./legit.pl init
Initialized empty legit repository in .legit
$ ls -d .legit
.legit
$ ./legit.pl init
legit.pl: error: .legit already exists
legit.pl may create initial files or directories inside .legit.
You do not have to use a particular representation to store the repository.
You do not have to create the same files or directory inside .legit as the reference
implementation.
legit.pl add filenames
The add command adds the contents of one or more files to the “index”.
Files are added to the repository in a two step process. The first step is adding them to the
index.
You will need to store files in the index somehow in the .legit sub-directory. For example you
might choose store them in a sub-directory of .legit.
Only ordinary files in the current directory can be added, and their names will always start with
an alphanumeric character ([a-zA-Z0-9]) and will only contain alpha-numeric characters plus ‘.’,
‘-‘ and ‘_’ characters.
The add command, and other legit.pl command, will not be given pathnames with slashes.
legit.pl commit -m message
The legit.pl commit command saves a copy of all files in the index to the repository.
A message describing the commit must be included as part of the commit command.
legit.pl commits are numbered (not hashes like git). You must match the numbering scheme.
You can assume the commit message is ASCII and does not contain new-line characters.
legit.pl log
legit.pl log prints one line for every commit that has been made to the repository.
Each line should contains the commit number and the commit message.
legit.pl show commit:filename
legit.pl show should print the contents of the specified file as of the specified commit.
If the commit is omitted the contents of the file in the index should be printed.
For example:
$ ./legit.pl init
Initialized empty legit repository in .legit
$ echo line 1 > a
$ echo hello world >b
$ ./legit.pl add a b
$ ./legit.pl commit -m ‘first commit’
Commited as commit 0
$ echo line 2 >>a
$ ./legit.pl add a
$ ./legit.pl commit -m ‘second commit’
Commited as commit 1
$ ./legit.pl log
1 second commit
0 first commit
$ echo line 3 >>a
$ ./legit.pl add a
$ echo line 4 >>a
$ ./legit.pl show 0:a
line 1
$ ./legit.pl show 1:a
line 1
line 2
$ ./legit.pl show :a
line 1
line 2
Legit Commands – Subset 1
legit.pl commit [-a] -m message
legit.pl commit can have -a options which causes all files already in the index to have their
current state added to the index.
legit.pl rm [–force] [–cached] filenames
legit.pl rm removes a file from the current directory or from the current directory and the index
legit.pl status
legit.pl status show the status of files in the current directory, index, and repository.
$ ./legit.pl init
Initialized empty legit repository in .legit
$ touch a b c d e f g h
$ ./legit.pl add a b c d e f
$ ./legit.pl commit -m ‘first commit’
Commited as commit 0
$ echo hello >a
$ echo hello >b
$ echo hello >c
$ ./legit.pl add a b
$ echo world >a
$ rm d
$ ./legit.pl rm e
$ ./legit.pl add g
$ ./legit.pl status
a – file modified and changes in index
b – file modified
c – changes in index
d – file deleted
e – deleted
f – same as repo
g – added to index
h – untracked
legit.pl – untracked
Legit Commands – Subset 2
legit.pl branch [-d] [branch-name]
legit.pl branch either creates a branch, deletes a branch or lists current branch-names.
legit.pl checkout branch-name
legit.pl checkout switches branches.
legit.pl merge branch-name|commit
legit.pl merge -m message adds the changes that have been made to specified branch or
commit to the index and commits them.
$ ./legit.pl init
Initialized empty legit repository in .legit
$ seq 1 7 >7.txt
$ ./legit.pl add 7.txt
$ ./legit.pl commit -m commit-1
Commited as commit 0
$ ./legit.pl branch b1
$ ./legit.pl checkout b1
Switched to branch ‘b1’
$ perl -pi -e ‘s/2/42/’ 7.txt
$ cat 7.txt
1
42
3
4
5
6
7
$ ./legit.pl commit -a -m commit-2
Commited as commit 1
$ ./legit.pl checkout master
Switched to branch ‘master’
$ cat 7.txt
1
2
If a file contains conflicting changes legit.pl merge produces an error message.
$ ./legit.pl init
Initialized empty legit repository in .legit
$ seq 1 7 >7.txt
$ ./legit.pl add 7.txt
$ ./legit.pl commit -m commit-1
Commited as commit 0
$ ./legit.pl branch b1
$ ./legit.pl checkout b1
Switched to branch ‘b1’
$ perl -pi -e ‘s/2/42/’ 7.txt
$ cat 7.txt
1
42
3
4
5
6
7
$ ./legit.pl commit -a -m commit-2
Commited as commit 1
$ ./legit.pl checkout master
Switched to branch ‘master’
$ cat 7.txt
1
2
3
Legit – Challenge
Often commits involve small changes to large files.
Can you use a data representations such that a commit involving a small change to a large file
use only small amount of extra space.
Diary
You must keep notes of each piece of you make work on this assignment. The notes should
include date, starting & finishing time, and a brief description of the work carried out. For
example:
Date Start Stop Activity Comments
29/09/17 16:00 17:30 coding implemented assignment statements
30/09/17 20:00 10:30 debugging found bug in while loops
Include these notes in the files you submit as an ASCII file named diary.txt.
Testing
As usual some autotests will be available:
$ 2041 autotest legit legit.pl
You will need to do most of the testing yourself.
Test Scripts
You should submit ten Shell scripts named test00.sh .. test09.sh which run legit
commands which test an aspect of Legit.
The test??.sh scripts do not have to be examples that your program implements successfully.
You may share your test examples with your friends but the ones you submit must be your own
creation.
The test scripts should show how you’ve thought about testing carefully.
Assumptions/Clarifications
Like all good programmers, you should make as few assumptions as possible. Your assignment
must be entirely written in Perl.
It must not run external programs (e.g. via system or back-quotes).
Your program will be run with version of Perl installed on CSE lab machines.
You may write scripts in Shell or other languages to assist in testing your assignment.
You may only use Perl packages which are installed on CSE’s lab computers.
You may submit multiple Perl files but the primary file must be named legit.pl.
You assume legit.pl is always run in the same directory as the repository and only files from
that directory are added to the repository.
You can assume that the directory in which legit.pl is run will not contain sub-directories apart
from .legit.
You can assume that the filenames in the directory in which legit.pl is run all start with an
alphanumeric character ([a-zA-Z0-9]) and will only contain alpha-numeric characters plus ‘.’, ‘-‘
and ‘_’.
The legit.pl which are given filenames (add, show, rm) with be given just the filename, not
pathnames with slashes .
You do not have to consider file permissions or other file metadata, for example you do not have
to ensure files created by a checkout command have the same permisisons as when they were
added.
Attribution of Work
This is an individual assignment. The work you submit must be your own work and only your
work apart from any exceptions explicitly include in the assignment specification above.
Joint work is not permitted.
You are only permitted to request help with the assignment in the course forum, help sessions or
from course lecturers or tutors.
Do not provide or show your assignment work to any other person (including by posting it on the
forum) apart from the teaching staff of COMP[29]041.
The work you submit must otherwise be entirely your own work. Submission of work partially or
completely derived from any other person or jointly written with any other person is not
permitted. The penalties for such an offence may include negative marks, automatic failure of
the course and possibly other academic discipline. Assignment submissions will be examined
both automatically and manually for such submissions.
We are required to inform scholarship authorities if students holding scholarships are involved in
an incident of plagiarism or other misconduct, and this may result in a loss of the scholarship.
Plagiarism or other misconduct can also result in loss of student visas.
If you knowingly provide or show your assignment work to another person for any reason, and
work derived from it is submitted you may be penalized, even if the work was submitted without
your knowledge or consent. This may apply even if your work is submitted by a third party
unknown to you.
Note, you will not be penalized if your work is taken without your consent or knowledge.
Submission of Work
You are required to submit intermediate versions of your assignment.
Every time you work on the assignment and make some progress you should copy your work to
your CSE account and submit it using the give command below.
It is fine if intermediate versions do not compile or otherwise fail submission tests.
Only the final submitted version of your assignment will be marked.
All these intermediate versions of your work will be placed in a git repo and made available to
you via a web interface at this URL, replace z5555555 with your zpass.
https://gitlab.cse.unsw.edu.au/z5555555/18s2-comp2041-
ass1_legit/commits/master
This will allow you to retrieve earlier versions of your code if needed.
You submit your work like this:
$ give cs2041 ass1_legit legit.pl test*.sh diary.txt
Assessment
This assignment will contribute 15 marks to your final COMP[29]041 mark
15% of the marks for assignment 1 will come from hand marking. These marks will be awarded
on the basis of clarity, commenting, elegance and style. In other words, you will be assessed on
how easy it is for a human to read and understand your program.
5% of the marks for assignment 1 will be based on the test suite you submit.
80% of the marks for assignment 1 will come from the performance of your code on a large
series of tests.
HD+ 100 All subsets working & challenge, legit.pl is beautiful, great test suite &
diary
HD (90) Subset 2 working, legit.pl is very clear & very readable, very good test
suite & diary
DN (80) Subset 1 working, legit.pl is good clear code, good test suite & diary
CR (70) Subset 0 working, legit.pl is good clear code, good test suite & diary
PS (60) Subset 0 passing some tests, legit.pl is reasonably readable, reasonable
test suite & diary
PS (55) Subset 0 working internally (storing data) put not passing tests
0% Knowingly providing your work to anyone and it is subsequently
submitted (by anyone).
0 FL for
COMP[29]041
Submitting any other person’s work. This includes joint work.
academic
misconduct
Submitting another person’s work without their consent. Paying another
person to do work for you.
The lecturer may vary the assessment scheme after inspecting the assignment submissions but
its likely to be broadly similar to the above.
Due Date
This assignment is tentatively due Wednesday 03 October 23:59:59
If your assignment is submitted after this date, each hour it is late reduces the maximum mark it
can achieve by 2%. For example if an assignment worth 74% was submitted 10 hours late, the
late submission would have no effect. If the same assignment was submitted 15 hours late it
would be awarded 70%, the maximum mark it can achieve at that time.
COMP[29]041 18s2: Software Construction is brought to you by
the School of Computer Science and Engineering at the University of New South Wales,
Sydney.
For all enquiries, please email the class account at cs2041@cse.unsw.edu.au
CRICOS Provider 00098G