This assignment aims to give you practice in Shell programming generally a clear concrete understanding of Gits 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 Shrug, 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 important commands. You will also be given a number of simplifying assumptions, which make your task easier.
Shrug is a contraction of Shell-running-git.
You must implement Shrug in Shell.
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 shrug-add should match the behaviour of 2041 shrug-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 its something you will likely need to do after you leave UNSW.
Discovering and matching the reference implementations behaviour is deliberately part of the assignment.
While the code in the reference implementation is fairly straight forward, 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. Andrew may fix the bug, or indicate that you do not need to match the reference implementations behaviour in this case.
Shrug Commands
Subset 0
Subset 0 commands must be implemented in POSIX-compatible Shell. See the Permitted Languages section for more information. shrug-init
The shrug-init command creates an empty Shrug repository.
shrug-init should create a directory named .shrug, 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 -d .shrug ls: cannot access .shrug: No such file or directory$ shrug-initInitialized empty shrug repository in .shrug$ ls -d .shrug.shrug $ shrug-init shrug-init: error: .shrug already exists |
shrug-init may create initial files or directories inside .shrug.
You do not have to use a particular representation to store the repository.
You do not have to create the same files or directories inside shrug-init as the reference implementation. shrug-add filenames
The shrug-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 .shrug sub-directory. For example, you might choose store them in a subdirectory of .shrug.
Only ordinary files in the current directory can be added. You can assume filenames start with an alphanumeric character ( a-zA-Z09 ) and will only contain alpha-numeric characters, plus ., – and _ characters.
The shrug-add command, and other Shrug commands, will not be given pathnames with slashes. shrug-commit -m message
The shrug-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.
Shrug 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. shrug-log
The shrug-log command prints a line for every commit made to the repository: each line should contain the commit number, and the commit message.
shrug-show commit :filename
The shrug-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.
For example:
| $ ./shrug-initInitialized empty shrug repository in .shrug$ echo line 1 > a$ echo hello world >b$ ./shrug-add a b$ ./shrug-commit -m first commitCommitted as commit 0$ echo line 2 >>a$ ./shrug-add a$ ./shrug-commit -m second commitCommitted as commit 1$ ./shrug-log1 second commit0 first commit$ echo line 3 >>a $ ./shrug-add a$ echo line 4 >>a $ ./shrug-show 0:a line 1$ ./shrug-show 1:a line 1 |
Subset 1
Subset 1 is more difficult. You will need 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. shrug-commit -a -m message
shrug-commit can 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. shrug-rm force cached filenames
shrug-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.
shrug-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 rms behaviour may also help.
The force option overrides this, and will carry out the removal even if the user will lose work. shrug-status
shrug-status shows the status of files in the current directory, the index, and the repository.
$ ./shrug-init
Initialized empty shrug repository in .shrug
$ touch a b c d e f g h
$ ./shrug-add a b c d e f
$ ./shrug-commit -m first commit
Committed as commit 0
$ echo hello >a
$ echo hello >b
$ echo hello >c
$ ./shrug-add a b
$ echo world >a
$ rm d
$ ./shrug-rm e
$ ./shrug-add g $ ./shrug-status a file changed, different changes staged for commit b file changed, changes staged for commit c file changed, changes not staged for commit d file deleted e deleted f same as repo
Subset 2
Subset 2 is extremely difficult. You will need 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. shrug-branch -d branch-name
shrug-branch either creates a branch, deletes a branch, or lists current branch names. shrug-checkout branch-name
shrug-checkout switches branches.
Note that, unlike Git, you can not specify a commit or a file: you can only specify a branch. shrug-merge branch-name|commit -m message
shrug-merge adds the changes that have been made to the specified branch or commit to the index, and commits them.
| $ ./shrug-initInitialized empty shrug repository in .shrug$ seq 1 7 >7.txt$ ./shrug-add 7.txt$ ./shrug-commit -m commit-1Committed as commit 0 $ ./shrug-branch b1$ ./shrug-checkout b1Switched to branch b1$ perl -pi -e s/2/42/ 7.txt$ cat 7.txt14234567$ ./shrug-commit -a -m commit-2Committed as commit 1$ ./shrug-checkout master |
If a file contains conflicting changes, shrug-merge produces an error message.
| $ ./shrug-initInitialized empty shrug repository in .shrug$ seq 1 7 >7.txt$ ./shrug-add 7.txt$ ./shrug-commit -m commit-1Committed as commit 0 $ ./shrug-branch b1$ ./shrug-checkout b1Switched to branch b1$ perl -pi -e s/2/42/ 7.txt$ cat 7.txt14234567$ ./shrug-commit -a -m commit-2Committed as commit 1$ ./shrug-checkout master |
Diary
You must keep notes on each piece of work you make on this assignment. The notes should include date, starting and finishing time, and a brief description of the work carried out. For example:
| Date | Start | Stop | Activity | Comments |
| 19/06/19 | 16 00 | 17 30 | coding | implemented basic commit functionality |
| 20/06/19 | 20 00 | 10 30 | debugging | found bug in command-line arguments |
Include these notes in the files you submit as an ASCII file named diary.txt.
Testing
Autotests
As usual, some autotests will be available:
$ 2041 autotest shrug shrug-*
You can also run only tests for a particular subset or an individual test:
$ 2041 autotest shrug subset1 shrug-*
$ 2041 autotest shrug subset1_13 shrug-*
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.
Test Scripts
You should submit ten Shell scripts, named test00.sh to test09.sh, which run shrug commands that test an aspect of Shrug.
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 youve thought about testing carefully. Permitted Languages
Your programs must be written entirely in POSIX-compatible shell.
Your programs will be run with dash(1), in /bin/dash. You can assume anything that works with the version of /bin/dash on CSE systems is POSIX compatible.
Start your programs with:
#!/bin/dash
If you want to run these scripts on your own machine for example, one running macOS which has dash(1) installed somewhere other than /bin, use:
#!/usr/bin/env dash
You are permitted to use any feature /bin/dash provides.
On CSE systems, /bin/sh is the Bash (Bourne-again shell) shell: /bin/sh is a symlink to /bin/bash. Bash implements many nonPOSIX extensions, including regular expressions and arrays. These will not work with /bin/dash, and you are not permitted to use these for the assignment.
You are not permitted to use Perl, Python or any language other than POSIX-compatible shell.
You are permitted to use only these external programs:
Only a few of the programs in the above list are likely to be useful for the assignment.
Note you are permitted to use built-in shell features including: cd, exit, for, if, read, shift and while.
If you wish to use an external program which is not in the above list, please ask in the class forum for it to be added.
You may submit extra Shell files. Assumptions/Clarifications
Like all good programmers, you should make as few assumptions as possible.
You can assume shrug commands are always run in the same directory as the repository, and only files from that directory are added to the repository.
You can assume the directory in which shrug commands are run will not contain sub-directories apart from .shrug.
You can assume where a branch name is expected a string will be supplied starting with an alphanumeric character ( a-zA-Z0-9 ), and only containing alphanumeric characters plus – and _. In additon a branch name will not be supplied which is entirely numeric. This allows brnach names to be distinguished from commits when merging.
You can assume where a filenames is expected a string will be supplied starting with an alphanumeric character ( a-zA-Z0-9 ) and only containing alpha-numeric characters, plus ., – and _ characters.
You can assume where a commit number is expected a string will be supplied which is a non-negative integer with no leading zeros. It will not contain white space or any other charcters except digits.
You can assume that shrug-add, shrug-show, and shrug-rm will be given just a 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 permissions as when they were added.
You do not have to handle concurrency. You can assume only one instance of any shrug command is running at any time.
You can assume that only the arguments described above are supplied to shrug commands. You do not have to handle other arguments.
You should match the output streams used by the reference implementations. It writes error messages to stderr: so should you.
You should match the exit status used by the reference implementation. It exits with status 1 after an error: so should you.
Autotest and automarking will run your scripts with a current working directory different to the directory containing the script. This may break Shell with code in extra files: if so, ask for help in the forum. The directory containing your submission will be in $PATH.
You can assume arguments will be in the position and order shown in the usage message from the reference implementation. Other orders and positions will not be tested. For example, here is the usage message for shrug-rm:
$ 2041 shrug-rm
usage: shrug-rm [force] [cached] <filenames>
So, you assume that if the force or cached options are present, they come before all filenames, and if they are both present the force option will come first. Change Log
Version 0.1 Initial release
(2020-06-26 14 00)
Version 0.2 bug in reference implementation fixed for shrug-status when file changed or removed after
(2020-07-06 21 00) being added
Version 0.3 bug in reference implementation fixed for shrug-show for file in index before first commit
(2020-07-06 16 00)
Version 0.4 add clarification about what can be supplied as arguments fix minor bug in reference
(2020-07-06 16 00) implementation for certain commit messages
When you think your program is working, you can use autotest to run some simple automated tests:
$ 2041 autotest shrug
Reviews
There are no reviews yet.