Skip to content

Latest commit

 

History

History
314 lines (232 loc) · 9.85 KB

USER_GUIDE.md

File metadata and controls

314 lines (232 loc) · 9.85 KB

Scribe User Guide

This guide will walk you through the initial setup for Scribe and provide details about all the commands.

Throughout this guide, it is assumed that the alias scribe has been set up for executing Scribe commands.

Refer to Creating an Alias section for instructions on creating an alias for Scribe.

Initial Setup

Before you can begin creating backups on your system, you need to provide some information to Scribe so that it knows where to store the backup files and which files and directories need to be included in the backup.
 

Step 1: Setting Backup Location

To set the backup location, run the following command:

$ scribe set-loc <path-to-backup-location>

Usage:

Setting the directory /home/user/backups/ as the backup location:

$ scribe set-loc /home/user/backups/

If the directory path you entered does not exist, Scribe will prompt if you wish to create the directory.
 

Step 2: Add Files and Directories to Backup List

To indicate which files and directories must be included in the backup, their respective paths should be added to the Backup List.

Command to add a path to the Backup List:

$ scribe add <path>

Usage:

$ scribe add /home/user/Documents/

 

Step 3: Create Backup

To create a backup, run the command:

$ scribe backup

 

Scribe Commands

Command Description
set-loc Set the path to the Backup Location
set-limit Set the maximum number of backups that can be stored
set-prefix Set the backup filename prefix
add Add a path to the Backup List
remove Remove a path from the Backup List
exclude Add a path to the Exclude List
remove-from-exclude Remove a path from the Exclude List
backup Create a backup
backup-loc Prints the Backup Location
backup-lim Prints the Backup Limit
config Prints the config settings
tar-verbose-on Turn on tar verbose output logging
tar-verbose-off Turn off tar verbose output logging
exclude-script Excludes the Scribe directory from backups
include-script Includes the Scribe directory in backups
ls-backup List all the paths in the Backup List
ls-exclude List all the paths in the Exclude List
clr-backup Clear all the paths in the Backup List
clr-exclude Clear all the paths in the Exclude List
clr-logs Clear all the log files
reset Reset the configurations to defaults and clear logs

1. Set Backup Location

The set-loc command is used to set the Backup Location.

If the provided directory path does not exist, the user will be prompted and asked whether they want to create the directory path.

$ scribe set-loc /home/user/backups/

2. Set Backup Limit

The set-limit command is used to set the BACKUP_LIMIT, which is the maximum number of backups that can be stored.

By default, the BACKUP_LIMIT is 3.

$ scribe set-limit 5

During backup creation, Scribe checks how many backup files exist in the Backup Location.
If the number of saved backup files is >= BACKUP_LIMIT, Scribe will delete the oldest backup.

3. Set Filename Prefix

The filenames for the backup file have the format "YYYY-MM-DD_HH:MM:SS.tar.gz".
If you want to add a specific prefix to the backup filename, you can set a the prefix using set-prefix.

The default Filename Prefix is an empty string.

$ scribe set-prefix "important-files-backup"

4. Add path to Backup List

Add a directory path or file path to the Backup List to include them in the backups.

If the path you are adding to the Backup List already exists in the Exclude List, the path will be removed from the Exclude List then added to the Backup List.

$ scribe add /home/user/Documents/ID-document.pdf

5. Remove path from Backup List

Remove paths you no longer want to include in backups from the Backup List.

$ scribe remove /home/user/Pictures/

6. Exclude File or Directory from Backups

Suppose you want to include your Documents directory in the backups but you do not want to the Documents/junk-files/ directory to be included in the backup.
You can add the absolute path of the junk-files directory to the Exclude List, this will exclude the directory from the backup.

$ scribe exclude /home/user/Documents/junk-files/

7. Remove a path from Exclude List

If you no longer want to exclude a file or directory from backups, remove it from the Exclude List.

$ scribe remove-from-exclude /home/user/Documents/junk-files/

8. Create a Backup

To create a backup, run the following command:

$ scribe backup

9. Toggling tar Verbose Logging

The tar verbose option prints out each file name as it is archived.
The output of the tar verbose will be stored in tar_verbose.log.

By default, tar verbose logging is off.

To turn on tar verbose logging:

$ scribe tar-verbose-on

To turn off tar verbose logging:

$ scribe tar-verbose-off

10. Include/Exclude Scribe Files

The Scribe files (config files, logs, scripts) are excluded from the backup by default.

To include the Scribe files in the backups (not recommended):

$ scribe include-script-files

To exclude the Scribe files from backups:

$ scribe exclude-script-files

11. Viewing Configurations

To print all the configuration settings:

$ scribe config

Print the Backup Location BACKUP_LOC:

$ scribe backup-loc

Print the Backup Limit BACKUP_LIMIT:

$ scribe backup-lim

12. Viewing Lists

Print contents of Backup List:

$ scribe ls-backup

Print contents of Exclude List:

$ scribe ls-exclude

13. Clearing Files

Clear the Backup List:

$ scribe clr-backup

Clear the Exclude List:

$ scribe clr-exclude

Clear Log Files:

$ scribe clr-logs

14. Reset Configurations

Reset all configurations to default values.

$ scribe reset

Creating an Alias

An alias is a kind of shorthand you can use in the terminal in place of a long command.

For example:
To create a backup, you will need to run the command:

$ /path/to/scribe.sh backup

Creating an alias allows you to assign a shorter alias to /path/to/scribe.sh.  

Creating an Alias in Linux:

  • Step 1: Open up the Terminal in the home directory.

  • Step 2: Enter ls -a and check if there is a .bashrc file listed.

  • Step 3: If the .bashrc file does not already exist, you should create one in the home directory by running touch .bashrc in the Terminal.

  • Step 4: Now run the command nano .bashrc to open up the file in the nano editor.

  • Step 5: On a fresh line at the end of the file, add the line:

    alias scribe='/path/to/scribe.sh'

    Make sure to replace path/to/scribe.sh with the path to wherever you stored the scribe.sh script on your system.

  • Step 6: Press Ctrl + X and then press Y to save the changes you made to the .bashrc file. Now close the Terminal.

Open up a fresh terminal for the changes to take effect.
 

Creating an Alias in macOS:

  • Step 1: Open up the Terminal in the home directory.

  • Step 2: Enter ls -a and check if there is a .zshrc file.

  • Step 3: If the .zshrc file does not already exist, you should create one in the home directory by running touch .zshrc in the Terminal.

  • Step 4: Now run the command nano .zshrc to open up the file in the nano editor.

  • Step 5: On a fresh line at the end of the file, add the line:

    alias scribe='/path/to/scribe.sh'

    Make sure to replace path/to/scribe.sh with the path to wherever you stored the scribe.sh script on your system.

  • Step 6: Press Cmd + X and then press Y to save the changes you made to the .zshrc file. Now close the Terminal.

Open up a fresh terminal for the changes to take effect.
 

You have successfully set up a short alias to run the scribe.sh script.

Now, you can run your commands for Scribe like so:

$ scribe backup

Notes

The backup location is excluded from backups by default.
This is done because it is redundant and costly to include previous backups in your new backup.

WARNING: DO NOT store other .tar.gz files in your backup location as they may accidentally be deleted. Scribe checks the number of .tar.gz files in the backup location to see if it is within the backup limit. If the number of .tar.gz files exceed the backup limit, the oldest .tar.gz file is deleted from the backup location.