COMP2041 Software Construction - Assignment 1: Pigs
Assignment 1: Pigs
Aims
This assignment aims to give you
- practice in Shell programming generally
- a clear concrete understanding of Git's core 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 Shell, 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 implement Pigs, a subset of the version control system Git.
Git is a very complex program that has many individual commands. You will implement only a few of the most important commands. You will also be given a number of simplifying assumptions, which make your task easier.
Pigs stands for POSIX Implementation of Git in Shell.
As you must implement Pigs in POSIX Shell (dash).
Interestingly, early versions of Git made heavy use of Shell and Perl.
Reference implementation
Many aspects of this assignment are not fully specified in this document; instead, you must match the behaviour of a reference implementation.
For example, your script pigs-add should match the behaviour of 2041 pigs-add exactly, including producing the same error messages.
Provision of a reference implementation is a common method to provide or define an operational specification, and it's something you will likely need to do after you leave UNSW.
Discovering and matching the reference implementation's behaviour is deliberately part of the assignment.
While the code in the reference implementation is fairly straightforward, reverse-engineering its behaviour is obviously not so simple, and is 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. We may fix the bug, or indicate that you do not need to match the reference implementation's behaviour in this case.
Pigs Commands
Subset 0
Subset 0 commands must be implemented in POSIX-compatible Shell.
See the Permitted Languages section for more information.
pigs-init
The pigs-init command creates an empty Pigs repository.
pigs-init should create a directory named .pig, which it will use to store the repository.
It should produce an error message if this directory already exists, or cannot be created.
You should match this, and other error messages exactly. For example:
ls -d .pig ls: cannot access '.pig': No such file or directory ./pigs-init Initialized empty pigs repository in .pig ls -d .pig .pig ./pigs-init ./pigs-init: error: .pig already exists
pigs-init may create initial files or directories inside .pig.
You do not have to use a particular representation to store the repository.
You do not have to (and should not) create the same files and directories inside .pig as the reference implementation.
You can create whatever files or directories inside .pig you wish.
Do not store information outside .pig
pigs-add filenames...
The pigs-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 .pig sub-directory.
For example, you might choose store them in a sub-directory of .pig.
Only ordinary files in the current directory can be added.
You can assume filenames start with an alphanumeric character ([a-zA-Z0-9]) and will only contain alpha-numeric characters, plus ., - and _ characters.
The pigs-add command, and other Pigs commands, will not be given pathnames with slashes.
pigs-commit -m message
The pigs-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.
Pigs commits are numbered sequentially: they are not hashes, like Git. You must match the numbering scheme.
You can assume the commit message is ASCII, does not contain new-line characters, and does not start with a - character.
pigs-log
The pigs-log command prints a line for every commit made to the repository.
Each line should contain the commit number and the commit message.
pigs-show [commit]:filename
The pigs-show should print the contents of the specified filename as of the specified commit.
If commit is omitted, the contents of the file in the index should be printed.
You can assume the commit, if specified, will be a non-negative integer.
Subset 0 examples
./pigs-init Initialized empty pigs repository in .pig echo line 1 > a echo hello world >b ./pigs-add a b ./pigs-commit -m 'first commit' Committed as commit 0 echo line 2 >>a ./pigs-add a ./pigs-commit -m 'second commit' Committed as commit 1 ./pigs-log 1 second commit 0 first commit echo line 3 >>a ./pigs-add a echo line 4 >>a ./pigs-show 0:a line 1 ./pigs-show 1:a line 1 line 2 ./pigs-show :a line 1 line 2 line 3 cat a line 1 line 2 line 3 line 4 ./pigs-show 0:b hello world ./pigs-show 1:b hello world
Subset 1
Subset 1 is more difficult. You will need to spend some time understanding the semantics (meaning) of these operations, by running the reference implementation, or researching the equivalent Git operations.
Note the assessment scheme recognises this difficulty.
Subset 1 commands must be implemented in POSIX-compatible Shell.
See the Permitted Languages section for more information.
pigs-commit [-a] -m message
pigs-commit can now have a -a option,
which causes all files already in the index to have their contents from the current directory added to the index before the commit.
pigs-rm [--force] [--cached] filenames...
pigs-rm removes a file from the index, or, from the current directory and the index.
If the --cached option is specified, the file is removed only from the index, and not from the current directory.
pigs-rm, like git rm, should stop the user accidentally losing work, and should give an error message instead if the removal would cause the user to lose work. You will need to experiment with the reference implementation to discover these error messages. Researching git rm's behaviour may also help.
The --force option overrides this, and will carry out the removal even if the user will lose work.
pigs-status
pigs-status shows the status of files in the current directory, the index, and the repository.
There are many different cases to consider for pigs-status.
You will need to experiment with the reference implementation to find them all.
Subset 1 examples
./pigs-init Initialized empty pigs repository in .pig touch a b c d e f g h ./pigs-add a b c d e f ./pigs-commit -m 'first commit' Committed as commit 0 echo hello >a echo hello >b ./pigs-commit -a -m 'second commit' Committed as commit 1 echo world >>a echo world >>b echo hello world >c ./pigs-add a echo world >>b rm d ./pigs-rm e ./pigs-add g ./pigs-status a - file changed, changes staged for commit b - file changed, changes not staged for commit c - file changed, changes not staged for commit d - file deleted e - deleted f - same as repo g - added to index h - untracked pigs-add - untracked pigs-branch - untracked pigs-checkout - untracked pigs-commit - untracked pigs-init - untracked pigs-log - untracked pigs-merge - untracked pigs-rm - untracked pigs-show - untracked pigs-status - untracked pigs.py - untracked
Subset 2
Subset 2 is extremely difficult. You will need to spend considerable time understanding the semantics of these operations, by running the reference implementation, and/or researching the equivalent Git operations.
Note the assessment scheme recognises this difficulty.
Subset 2 commands must be implemented in POSIX-compatible Shell.
See the Permitted Languages section for more information.
pigs-branch [-d] [branch-name]
pigs-branch either creates a branch, deletes a branch, or lists current branch names.
If branch-name is omitted, the names of all branches are listed.
If branch-name is specified, then a branch with that name is created or deleted,
depending on whether the -d option is specified.
pigs-checkout branch-name
pigs-checkout switches branches.
Note that, unlike Git, you can not specify a commit or a file: you can only specify a branch.
pigs-merge (branch-name|commit-number) -m message
pigs-merge adds the changes that have been made to the specified branch or commit to the index, and commits them.
Subset 2 examples
./pigs-init Initialized empty pigs repository in .pig seq 1 7 >7.txt ./pigs-add 7.txt ./pigs-commit -m commit-1 Committed as commit 0 ./pigs-branch b1 ./pigs-checkout b1 Switched to branch 'b1' sed -Ei 's/2/42/' 7.txt cat 7.txt 1 42 3 4 5 6 7 ./pigs-commit -a -m commit-2 Committed as commit 1 ./pigs-checkout master Switched to branch 'master' cat 7.txt 1 2 3 4 5 6 7 ./pigs-merge b1 -m merge-message Fast-forward: no commit created cat 7.txt 1 42 3 4 5 6 7
If a file has been changed in both branches pigs-merge produces an error message.
Note: if a file has been changed in both branches git examines which lines have been changed and combines the changes if possible. Pigs doe not do this, for example:
./pigs-init Initialized empty pigs repository in .pig seq 1 7 >7.txt ./pigs-add 7.txt ./pigs-commit -m commit-1 Committed as commit 0 ./pigs-branch b1 ./pigs-checkout b1 Switched to branch 'b1' sed -Ei 's/2/42/' 7.txt cat 7.txt 1 42 3 4 5 6 7 ./pigs-commit -a -m commit-2 Committed as commit 1 ./pigs-checkout master Switched to branch 'master' cat 7.txt 1 2 3 4 5 6 7 sed -Ei 's/5/24/' 7.txt cat 7.txt 1 2 3 4 24 6 7 ./pigs-commit -a -m commit-3 Committed as commit 2 ./pigs-merge b1 -m merge-message ./pigs-merge: error: These files can not be merged: 7.txt cat 7.txt 1 2 3 4 24 6 7
Testing
Autotests
As usual, some autotests will be available:
2041 autotest pigs pigs-* ...
You can also run only tests for a particular subset or an individual test:
2041 autotest pigs subset1 pigs-* ... 2041 autotest pigs subset1_13 pigs-* ...
If you are using extra Shell files, include them on the autotest command line.
Autotest and automarking will run your scripts with a current working directory different to the directory containing the script. The directory containing your submission will be in $PATH.
You will need to do most of the testing yourself.
