Assignment I

You are a solo developer tasked with building, versioning, and documenting a robust bash script to automate the backup of your important files. You will use Git and GitHub not for collaboration, but for professional version control, feature development, and project tracking.

Learning Objectives

• Design and implement a complex bash script to solve a real-world problem

• Master a professional, branching-based Git workflow for solo development

• Create clear technical documentation

• Use GitHub Issues for personal task management and milestone tracking

Note: Read all three tasks before you start coding!

I. Foundation and Repository Setup

Task 1

Create a private GitHub repository named autobass and initialize it with a markdown file called README.md and a .gitignore file for shell scripts.

Task 2

Write a minimal viable product script, archive.sh, which must have the following functionality:

1. It must accept two command-line arguments: (i) a source directory, and (ii) a target directory.

2. It must create a new folder in the target directory with a timestamp (e.g., backup_20250915_124506/).

3. It must copy all files from the source to this new target folder using rsync or cp.

4. The script must have a --help or -h flag that prints usage instructions.

Task 3

Make your initial commits on the remote repository. Your commit messages must be descriptive (e.g., "added basic script structure" or "initialized README"). Throughout the development of the archiving script, there must be at least one commit for each function. Since there are four functions listed in Task 2, your use of Git must show at least four distinct commits with adequate corresponding messages. Commit amends do not count towards this.

II. Feature Isolation

You will develop each of the following features in its own dedicated branch, and you must use GitHub Issues to create an issue for each feature, and close the issue via a commit message when the feature is merged. You will see "Issues" as the second tab from the left, once you visit the GitHub repository in a browser.

Feature 1: Compression and Logging

This feature must be implemented on a branch called compression. In this branch, you must accomplish the following:

1. Modify the script to create a compressed .tar.gz archive instead of a plain backup folder in the target directory. The archive filename must include the timestamp (e.g., backup_20250915_144022.tar.gz).

2. The script must be written to produce informative logs. The logging functions must capture all the following information to the terminal (stdout/stderr), and also append it to the archive.log file with a timestamp for every message:

   1. Start of execution: "INFO: [timestamp] archive script started."

   2. Source check: "ERROR: [timestamp] Source directory (/path/to/source) does not exist or is not readable. Exiting." (Should exit with an error code if this fails).

   3. Target check: "ERROR: [timestamp] Target directory (/path/to/target) does not exist or could not be created. Exiting." (Should exit with an error code if this fails).

   4. Confirmation of action: "INFO: [timestamp] Backing up from <source> to <target_file.tar.gz>."

   5. Completion success: "INFO: [timestamp] Backup completed successfully."

   6. Completion failure: "ERROR: [timestamp] Backup failed during compression." (Should exit with an error code).

   7. Dry-run notice: If the dry-run feature (see the tasks in Feature 3) is implemented, it must output "INFO: [timestamp] Dry-run enabled. Simulating backup."

   8. Any other critical error: "ERROR: <placeholder>" (Put the actual error message in the placeholder)

Feature 2: Configuration File

This feature must be implemented on a branch called config.  In this branch, you must accomplish the following:

1. Move the source and target paths into a configuration file (archive.conf).

2. The script must source this file. If no command-line arguments are provided, it should use the values from this configuration file.

Feature 3: Exclusions and Dry-Run

This feature must be implemented on a branch called exclusions.  In this branch, you must accomplish the following:

1. Add support for an exclude file called .bassignore, which lists patterns of files to skip (e.g., *.log, tmp/).

2. Add a --dry-run or -d flag that shows the user what would be backed up without actually performing the operation.

Git Workflow for each feature

1. git checkout -b <feature> (from main)

2. Write the code for the feature (e.g., for the dry-run and exclusion feature in the exclusions branch after you have checked it out from main)

3. git add . and git commit -m "feat: <description of feature>. Closes #1" (this links the message to the GitHub issue)

4. git checkout main (switch back to main)

5. git merge <feature> (merge the feature branch into main)

6. git branch -d <feature> (delete the feature branch)

III. Testing, Refinement, and Documentation

Task 1 (Bash)

Test your script thoroughly. Create a dummy directory with subfolders, text files, temporary files (.tmp), and log files. Run your script with different flags to ensure everything works (e.g., test the dry-run mode, test that excluded content is actually skipped).

Task 2 (Git)

Create a v1.0 tag for your first stable release. Do not forget to include a commit message that describes the main features included in this release.

Task 3 (Documentation)

Transform your README.md into a professional user manual. It must at least include:

• a brief (4-5 lines) project description;

• installation instructions, describing how to download and the script executable (imagine a user who has basic knowledge of a terminal, but does not know shell scripting);

• usage, with examples of every possible way to run the script (i.e., with arguments, with config, with dry-run); and

• configuration, explaining the role of the config file and the  format of the exclude file .bassignore.

Task 4

Create a final GitHub issue titled "Prepare for submission." In this issue, write a short paragraph (as a comment) reflecting on this project:

• What was the most challenging part for you?

• What features would you add if you had more time?

Do not close this issue.

What to submit?

Your submission must be on Brightspace. It must be a single plain text (.txt) file containing (i) the URL to your GitHub repository, and (ii) your GitHub username.

Note: You must add cse337collaborator@cs.stonybrook.edu as a collaborator to your GitHub repository. This is required for us to see your entire commit history, branching structure, issues, tags, and your actual code. Without this, we cannot grade your assignment!