Merge pull request #9 from DeNepo/01-debug-your-script

add 01-debug-your-script

01-debug-your-script/0-examples/00.md

@@ -0,0 +1,24 @@
+# How to Debug Your Bash Script
+
+## Overview
+
+Debugging is the process of identifying and removing errors and/or bugs from a script.
+For Bash scripts, one helpful tool for debugging is `shellcheck`.
+
+### Using `shellcheck`
+
+- You can use the browser version of shellcheck at [ShellCheck.net](https://www.shellcheck.net/).
+- To install shellcheck, visit the [ShellCheck GitHub repository](https://github.com/koalaman/shellcheck) and follow the instructions.
+- It can also be used as a plugin (ShellCheck) for various editors including VS Code.
+
+To run shellcheck from the command line, use the following command:
+
+```bash
+shellcheck 1.sh
+```
+
+### Limitations of `shellcheck`
+
+- It cannot detect issues with the environment that the script is running in.
+- It cannot detect how the permissions are set on the file.
+- It won't be able to tell you if specific packages are required to run the script.

01-debug-your-script/0-examples/01.md

@@ -0,0 +1,59 @@
+# Common Error Types in Bash Scripting
+
+When writing Bash scripts, it's common to encounter various types of errors. Understanding these errors and how to address them is crucial for successful script execution. Below are some of the most common error types along with examples and solutions:
+
+## 1. Syntax Errors
+
+Syntax errors occur due to mistakes in the script's syntax, leading to unexpected behavior or failure to execute.
+
+**Example:**
+
+```bash
+Syntax Error: unexpected end of file
+```
+
+## 2. Not Found Errors
+
+Not found errors occur when the script attempts to access a non-existent file or directory.
+
+**Example:**
+
+```bash
+No such file or directory
+```
+
+## 3. File Exists Errors
+
+File exists errors occur when the script tries to create a file or directory that already exists.
+
+**Example:**
+
+```bash
+File exists
+```
+
+## 4. Permission Denied Errors
+
+Permission denied errors arise when the script lacks the necessary permissions for a specific operation.
+
+**Example:**
+
+```bash
+Permission denied
+```
+
+**Solution:**
+This error can often be resolved by using the `sudo` command before the operation that requires elevated permissions.
+
+## 5. Command Not Found Errors
+
+Command not found errors occur when the script attempts to execute a command that is not in the system's PATH.
+
+**Example:**
+
+```bash
+Command not found
+```
+
+**Solution:**
+Ensure that the command is installed on the system or provide the full path to the command in the script.

01-debug-your-script/0-examples/01.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# Author: Samir M.
+# Date: 2024-03-13
+# Modified: 2024-03-14
+# Description: Common error types in Bash
+# Usage: ./01.sh
+
+#------------------------------------------------------------------#
+
+# 1. Syntax Errors
+
+# Example of Syntax Error:
+# echo "Hello World # Syntax error: missing closing double quote
+
+# 2. Not Found Errors
+
+# Example of Not Found Error: Attempting to access a non-existent directory
+ls /non_existent_directory # No such file or directory
+
+# 3. File Exists Errors
+
+# Example of File Exists Error: Attempting to create a file that already exists
+touch 01.sh # File exists
+
+# 4. Permission Denied Errors
+
+# Example of Permission Denied Error: Attempting to write to a directory without proper permissions
+echo "Hello" >/root/test.txt # Permission denied
+
+# 5. Command Not Found Errors
+
+# Example of Command Not Found Error: Typo in the command
+hello # Command not found
+
+# Ensure that the command is correctly spelled or installed
+
+#------------------------------------------------------------------#
+
+exit 0

01-debug-your-script/0-examples/02.md

@@ -0,0 +1,56 @@
+# Finding Help in Bash
+
+When working with Bash scripts, knowing how to find help for commands and understanding different types of commands is essential for efficient script development and troubleshooting.
+
+## Finding Help
+
+There are several methods to find help for commands in Bash:
+
+- **Using the `man` Command**: The `man` command displays the manual page for a given command.
+
+- **Using the `help` Command**: The `help` command provides help information for shell built-in commands.
+
+- **Using the `info` Command**: The `info` command displays detailed information (info page) for a given command.
+
+### Types of Commands
+
+Commands in Bash can be categorized into two main types:
+
+1. **Internal Commands**: These are commands built into the shell itself, such as `echo`.
+
+2. **External Commands**: These are commands that are not built into the shell and typically reside in separate executable files, such as `ls`
+
+### Determining Command Types
+
+To determine the type of a command, you can use the `type` command:
+
+```bash
+type -a echo # echo is a shell builtin
+```
+
+The `-a` option displays all information about the command, including its type.
+
+### Using the `help` Command
+
+The `help` command is specifically designed to provide help information for `shell built-in commands`. Here are some useful options:
+
+- `help <command>`: Display help information for the specified command.
+- `help -d <command>`: Display the short description of the command.
+- `help -s <command>`: Display the syntax of the command.
+
+### Using the `man` Command
+
+The `man` command is used to display the manual page for `external commands`. It offers several options:
+
+- `man <command>`: Display the manual page for the specified command.
+- `man -k <keyword>`: Search for manual pages containing the specified keyword.
+- `man -K <keyword>`: Display the manual page for the specified keyword (more detailed).
+
+### Using the `info` Command
+
+The `info` command provides detailed information (info page) for `external commands`. Here are some options:
+
+- `info <command>`: Display the info page for the specified command.
+- `info -d <command>`: Display the short description of the command.
+- `info -s <command>`: Display the syntax of the command.
+- `info -k <keyword>`: Search for info pages containing the specified keyword.

01-debug-your-script/0-examples/02.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Author: Samir M.
+# Date: 2024-03-14
+# Modified: 2024-03-14
+# Description: Finding help in Bash
+# Usage: ./02.sh
+
+#------------------------------------------------------------#
+
+# There are several ways to find help in Bash
+# 1. help Command
+# 2. man command
+# 3. info command
+
+# Which one to use depnds on the type of command and the level of detail required
+# There are two types of commands: Internal and External, we can use the `type` command
+# to determine the type of a command
+
+# Internal Commands
+type -a echo # Determine the type of the 'echo' command
+
+# External Commands
+type -a ls # Determine the type of the 'ls' command
+
+# we use `help` command with the `internal commands`
+# we use `man` and `info` command with the `external commands`
+
+# both `man` and `info` provide documentation for commands and programs.
+# `man` command offer a simpler, text-based interface with essential information.
+# `info` command provide a more structured, hierarchical format with comprehensive documentation,
+# particularly for GNU software.
+# The choice between `man` and `info` depends on the specific documentation available for
+# the command or program you are interested in and your preferred style of navigation and presentation.
+
+#------------------------------------------------------------#
+
+exit 0

01-debug-your-script/0-examples/03.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Author: Samir M.
+# Date: 2024-03-14
+# Modified: 2024-03-14
+# Description: the help command
+# Usage: ./03.sh
+
+#------------------------------------------------------------#
+
+# The `help` command is  used with Internal Commands(built-in command) in Bash.
+# Example: Display help information for the 'echo' command
+echo "Displaying help information for the 'echo' command:"
+help echo
+
+# Example: Displaying syntax of the 'echo' command
+echo "Displaying syntax of the 'echo' command:"
+help -s echo
+
+#------------------------------------------------------------#
+
+exit 0

01-debug-your-script/0-examples/04.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# Author: Samir M.
+# Date: 2024-03-14
+# Modified: 2024-03-14
+# Description: the man command
+# Usage: ./04.sh
+
+#------------------------------------------------------------#
+
+# Example: Display the manual page for the 'ls' command
+echo "Displaying the manual page for the 'ls' command:"
+man ls
+
+# Example: Search for manual pages containing the keyword 'ls'
+echo "Searching for manual pages containing the keyword 'ls':"
+man -k ls
+
+# Example: Display the manual page for the keyword 'ls' (more detailed)
+echo "Displaying the manual page for the keyword 'ls' (more detailed):"
+man -K ls
+
+#------------------------------------------------------------#
+
+exit 0

01-debug-your-script/0-examples/05.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# Author: Samir M.
+# Date: 2024-03-14
+# Modified: 2024-03-14
+# Description: the info command
+# Usage: ./05.sh
+
+#------------------------------------------------------------#
+
+# Example: Display the info page for the 'ls' command
+echo "Displaying the info page for the 'ls' command:"
+info ls
+
+# Example: Displaying short description of the 'ls' command
+echo "Displaying short description of the 'ls' command:"
+info -d ls
+
+# Example: Displaying syntax of the 'ls' command
+echo "Displaying syntax of the 'ls' command:"
+info -s ls
+
+# Example: Search for info pages containing the keyword 'ls'
+echo "Searching for info pages containing the keyword 'ls':"
+info -k ls
+
+#------------------------------------------------------------#
+
+exit 0

01-debug-your-script/1-blanks/01.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+# Author: ________
+# Date: __________
+# Modified: ___________
+# Description: Common error types in Bash
+# Usage: ./01.sh
+
+#------------------------------------------------------------------#
+
+# 1. Syntax Errors
+
+# Example of Syntax Error:
+# echo "Hello World # Syntax error: __________
+
+# 2. Not Found Errors
+
+# Example of Not Found Error: Attempting to access a non-existent _________
+ls _________ # _____________
+
+# 3. File Exists Errors
+
+# Example of File Exists Error: Attempting to create a file that already ________
+touch ________ # ________
+
+# 4. Permission Denied Errors
+
+# Example of Permission Denied Error: Attempting to write to a directory without proper __________
+echo "Hello" >/root/test.txt # ______________
+
+# 5. Command Not Found Errors
+
+# Example of Command Not Found Error: ________ in the ________
+hello # _______________
+
+# Ensure that the command is correctly spelled or installed
+
+#------------------------------------------------------------------#
+
+exit 0
+
+

01-debug-your-script/1-blanks/02.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Author: ________
+# Date: __________
+# Modified: ___________
+# Description: Finding help in Bash
+# Usage: ./02.sh
+
+#------------------------------------------------------------#
+
+# There are several ways to find help in Bash
+# 1. ______ Command
+# 2. ______ command
+# 3. ______ command
+
+# Which one to use depends on the type of command and the level of detail required
+# There are two types of commands: Internal and External, we can use the `type` command
+# to determine the type of a command
+
+# Internal Commands
+type -a echo # Determine the type of the 'echo' command
+
+# External Commands
+type -a ls # Determine the type of the 'ls' command
+
+# we use `help` command with the `internal commands`
+# we use `man` and `info` command with the `external commands`
+
+# both `man` and `info` provide documentation for commands and programs.
+# `man` command offer a simpler, text-based interface with essential information.
+# `info` command provide a more structured, hierarchical format with comprehensive documentation,
+# particularly for GNU software.
+# The choice between `man` and `info` depends on the specific documentation available for
+# the command or program you are interested in and your preferred style of navigation and presentation.
+
+#------------------------------------------------------------#
+
+exit 0