Mini Bash VCS

A pure Bash mini VCS that supports multi-repo management, locking, role-based permissions, history/rollback, release packaging, build logging, and automation. The entry point is ./vcs.sh.

Quick Start

# initialize repo under .vcs/repos/demo
./vcs.sh init demo

# add files (from cwd workspace)
./vcs.sh -r demo add path/to/file.txt

# manage permissions
./vcs.sh -r demo auth add-user alice writer

# checkout/edit/checkin
env VCS_FAKE_USER=alice ./vcs.sh -r demo checkout path/to/file.txt
$EDITOR path/to/file.txt
env VCS_FAKE_USER=alice ./vcs.sh -r demo checkin path/to/file.txt -m "message"

Commands

• init <name>: create repository structure under .vcs/repos/<name>.
• list-repos: list known repositories.
• add <files...>: start tracking files (stores initial snapshot).
• checkout <file>: acquire lock (requires writer/admin role).
• edit <file>: open file in $EDITOR (defaults to nano); requires lock ownership.
• checkin <file> -m "<message>": record change (diffs with periodic snapshots) and release lock.
• status [--long]: show tracked/untracked/locked/modified files.
• log [--file f] [--since ts] [--until ts]: view repo or file log.
• auth add-user|set-role|ls: manage reader/writer/admin roles.
• history <file>: show per-file change history.
• revert <file> <objectId>: restore file to a previous object version (records new snapshot).
• release create|ls|extract: package latest versions as .tar.gz or inspect releases.
• build [--cmd "<command>"]: run build in workspace, log output to meta/build.log.
• unlock <file> / force-unlock <file>: release locks (force requires admin).
• help / help <command>: show usage.

Global flags:

• -r <repo> selects repository (defaults to basename $PWD).
• -h|--help prints summary.

Permissions & Locking

Roles live in meta/users per repo; defaults to granting the creator admin. Readers can inspect but not checkout/checkin. Writers/admins can edit; only admins may use force-unlock. Lock files record owner/timestamp; backups are taken automatically during checkout/checkin.

Object Storage

• First add creates a full snapshot in objects/data/.
• Subsequent checkin creates diffs (diff -u). A full snapshot is automatically stored every SNAPSHOT_INTERVAL commits or if file exceeds SNAPSHOT_SIZE_LIMIT bytes, keeping patch chains short.
• Logs follow <ISO8601> <user> <action> <file> <objectId> "<message>" format and are written both repo-wide and per-file.

Testing

Run the non-interactive test harness:

./test.sh
# or via make
make test

The suite creates a temp repo, exercises locking/roles/history/revert/releases/build, and exits non-zero if any step fails.

Packaging

Produce the required submission bundle (submission.zip) via:

./package.sh
# or
make package

The archive includes vcs.sh, test.sh, package.sh, and Makefile. Clean up with make clean.