From 55966a541b15429012e02ec044aab8df5368bd44 Mon Sep 17 00:00:00 2001 From: Veritia Date: Thu, 27 Nov 2025 17:19:02 +0000 Subject: [PATCH 01/12] Add Intro to command line turotial --- docs/intro_to_command_line_tutorial.md | 230 +++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 docs/intro_to_command_line_tutorial.md diff --git a/docs/intro_to_command_line_tutorial.md b/docs/intro_to_command_line_tutorial.md new file mode 100644 index 000000000..ed746aab8 --- /dev/null +++ b/docs/intro_to_command_line_tutorial.md @@ -0,0 +1,230 @@ +# Command Line Basics + +This tutorial introduces the minimal set of command line concepts needed to use or develop **Click-based command line interfaces (CLIs)**. +It is written for beginners who may have little or no command line experience. +All examples provide commands for both macOS/Linux (Bash) and Windows (PowerShell). + +```{contents} +:depth: 2 +:local: +``` + +## Understanding Your System + +Before using the command line, it's important to know which operating system and shell you are running. +Different systems have slightly different commands, so this knowledge will help you follow tutorials and avoid errors. + +**macOS / Linux** +```bash +uname -a # Display OS version and system information +```` + +**Windows (PowerShell)** +```powershell +Get-ComputerInfo | Select-Object WindowsVersion, OsName, OsBuildNumber +```` + +> **Tip** +> +> Knowing your OS helps you troubleshoot problems more effectively. + + +> **Common mistake:** +> +> Trying to run a Linux command on Windows without an appropriate shell like WSL. + + +## Files, Directories, and Paths +Command-line tools interact with files and directories: +- **File**: A piece of stored data (text, code, image, etc.). +- **Directory (folder)**: A container for files or other directories. +- **Path**: A reference to a file or directory location, either relative or absolute. + +**macOS / Linux** +```bash +pwd # Print working directory +ls # List files and directories +```` + +**Windows (PowerShell)** +```powershell +Get-Location +Get-ChildItem +```` + +> **Tip** +> +>Relative paths start from your current directory; absolute paths start from the root. + + +> **Common mistake:** +> +> Confusing relative and absolute paths, which can cause “file not found” errors. + + +## Navigating the Filesystem +You can move around directories using the `cd` command: + +**macOS / Linux** +```bash +cd /tmp # Go to /tmp +cd ~ # Go to your home directory +cd .. # Go up one directory level +```` + +**Windows (PowerShell)** +```powershell +cd C:\Temp +cd $HOME +cd .. +```` + +> **Tip** +> +> Use `pwd` (Linux/macOS) or `Get-Location` (Windows) to check your current directory. + + +> **Common mistake:** +> +> Forgetting that commands like `cd` are case-sensitive on Linux/macOS. + + +## Creating Directories +To organize your files, create a directory using: + +**macOS / Linux** +```bash +mkdir myproject # Make a new directory called myproject +```` + +**Windows (PowerShell)** +```powershell +New-Item -ItemType Directory -Name myproject +```` + +> **Tip** +> +>You can create nested directories with `mkdir -p myproject/subdir` on Linux/macOS. + + +> **Common mistake:** +> +> Trying to create a directory that already exists will fail unless using the `-p` flag. + + +## Creating Files +Create an empty file inside a directory: + +**macOS / Linux** +```bash +touch myproject/hello.txt +```` + +**Windows (PowerShell)** +```powershell +New-Item -ItemType File myproject/hello.txt +```` + +> **Tip** +> +>Files can be created in any directory you have write permissions for. + + +> **Common mistake:** +> +> Forgetting to specify the directory and ending up creating the file in the wrong place. + + +## Editing Files +You can open and edit files with a text editor of your choice: + +**macOS / Linux** +```bash +nano myproject/hello.txt +```` + +**Windows (PowerShell)** +```powershell +notepad myproject/hello.txt +```` + +Add the following line to the file: + +``` +Hello from the command line! +``` + +> **Tip** +> +>Try a simple editor like nano or notepad first; later you can use VS Code for larger projects. + + +> **Common mistake:** +> +> Forgetting to save the file before exiting the editor. + + +## Viewing File Contents +Check the contents of a file using these commands: + +**macOS / Linux** +```bash +cat myproject/hello.txt +```` + +**Windows (PowerShell)** +```powershell +Get-Content myproject/hello.txt +```` + +> **Tip** +> +>Use these commands to quickly verify your edits. + + +> **Common mistake:** +> +> Using `cat` on very large files can flood the terminal; use `less` instead. + + +## Searching Within Files +Search for specific text inside a file: + +**macOS / Linux** +```bash +grep "Hello" myproject/hello.txt +```` + +**Windows (PowerShell)** +```powershell +Select-String -Pattern "Hello" -Path myproject/hello.txt +```` +> **Tip** +> +> Use search to verify that text exists or to debug issues in configuration files. + + +> **Common mistake:** +> +> Forgetting to quote search patterns with spaces, which can break the command. + + +## Getting Help for a CLI + +Click-based CLIs support the `--help` option, which lists commands and options: +``` +mycli --help +``` + +If the CLI is implemented as a Python module: + +``` +python -m mycli --help +``` + +## Further Reading + +- [SW Carpentry](https://swcarpentry.github.io/shell-novice/) +- [Microsoft Powershell](https://learn.microsoft.com/powershell/) +- [Ubuntu](https://ubuntu.com/tutorials/command-line-for-beginners) +- [Python](https://docs.python.org/3/tutorial/venv.html) From 7fe35074006319b9b15b4e0eed19c31077cd46ae Mon Sep 17 00:00:00 2001 From: Veritia Date: Thu, 27 Nov 2025 17:27:33 +0000 Subject: [PATCH 02/12] Trigger CI rebuild From 7eb012d731819403a8f5042e55274b308b1d9a5c Mon Sep 17 00:00:00 2001 From: Veritia Date: Thu, 27 Nov 2025 17:34:48 +0000 Subject: [PATCH 03/12] Trigger CI rebuild From 06967f0dc1ce9a2f165ca7701d9495fb88f53b52 Mon Sep 17 00:00:00 2001 From: Veritia Date: Thu, 27 Nov 2025 17:50:04 +0000 Subject: [PATCH 04/12] Add command line tutorial to toctree --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index a6bcd8416..e3eccfa89 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -71,6 +71,7 @@ Tutorials quickstart virtualenv + intro_to_command_line_tutorial How to Guides --------------- From 8d50e71c23f0ce59f9e0b41f73ee5061c2847c2d Mon Sep 17 00:00:00 2001 From: Veritia Date: Thu, 27 Nov 2025 17:52:10 +0000 Subject: [PATCH 05/12] Trigger Read the Docs rebuild From 634dab4b355fcc29e179a1d822c0e913f8515409 Mon Sep 17 00:00:00 2001 From: Venom Date: Sat, 20 Dec 2025 15:34:19 +0100 Subject: [PATCH 06/12] docs: modified the introduction title and wording. Added 4 extra sections to provide more context to a beginner what a cli is, and added the requirements needed to follow the tutorial --- docs/intro_to_command_line_tutorial.md | 126 +++++++++++++++++-------- 1 file changed, 86 insertions(+), 40 deletions(-) diff --git a/docs/intro_to_command_line_tutorial.md b/docs/intro_to_command_line_tutorial.md index ed746aab8..8e231ae44 100644 --- a/docs/intro_to_command_line_tutorial.md +++ b/docs/intro_to_command_line_tutorial.md @@ -1,152 +1,196 @@ -# Command Line Basics +# Command line basics — Introduction to command line interfaces (CLIs) -This tutorial introduces the minimal set of command line concepts needed to use or develop **Click-based command line interfaces (CLIs)**. +This short, hands-on tutorial gives developers the minimal set of command-line skills needed to start using or building Click-based CLIs. It is written for beginners who may have little or no command line experience. -All examples provide commands for both macOS/Linux (Bash) and Windows (PowerShell). +All examples provide commands for both macOS/Linux (Bash) and Windows (cmd). ```{contents} :depth: 2 :local: ``` +First Let's understand what a command line interface is. + +## What is a Command Line Interface (CLI)? + +A Command Line Interface (CLI) is a text-based way to interact with your computer. +Instead of clicking icons or buttons, you type commands into a terminal or console window. +CLIs are powerful tools for developers and system administrators because they allow for automation, scripting, and remote access to systems. +Examples of popular CLIs include: + +- **Bash** (Bourne Again SHell): Common on macOS and Linux systems. +- **cmd.exe**: The traditional command prompt on Windows. + +## How does it work? + +Users type commands into a CLI shell (e.g., Bash, cmd), which interprets and executes them: + +**Shell Role:** Acts as an intermediary between the user and the operating system
+**Command Process:** +The shell parses the command, identifying the action, options, and arguments. It locates the command in the system’s PATH and executes it. The system returns output (e.g., data, error messages) to the CLI. + +## What you will learn + +By the end of this tutorial, you will be able to: + +- Identify your OS and shell +- See the difference between files and directories, and how paths work +- Move around the filesystem, create a directory and a file +- Edit the file and print its contents in the terminal +- Search inside a file (grep-style) +- View a CLI's help output + +## Prerequisites + +- A computer with a shell (macOS / Linux / Windows). +- A text editor you can run from the terminal (nano, vi, notepad, code, etc.). + ## Understanding Your System Before using the command line, it's important to know which operating system and shell you are running. Different systems have slightly different commands, so this knowledge will help you follow tutorials and avoid errors. **macOS / Linux** + ```bash uname -a # Display OS version and system information -```` +``` **Windows (PowerShell)** + ```powershell Get-ComputerInfo | Select-Object WindowsVersion, OsName, OsBuildNumber -```` +``` > **Tip** > > Knowing your OS helps you troubleshoot problems more effectively. - > **Common mistake:** > > Trying to run a Linux command on Windows without an appropriate shell like WSL. - ## Files, Directories, and Paths + Command-line tools interact with files and directories: + - **File**: A piece of stored data (text, code, image, etc.). - **Directory (folder)**: A container for files or other directories. - **Path**: A reference to a file or directory location, either relative or absolute. **macOS / Linux** + ```bash pwd # Print working directory ls # List files and directories -```` +``` **Windows (PowerShell)** + ```powershell Get-Location Get-ChildItem -```` +``` > **Tip** > ->Relative paths start from your current directory; absolute paths start from the root. - +> Relative paths start from your current directory; absolute paths start from the root. > **Common mistake:** > > Confusing relative and absolute paths, which can cause “file not found” errors. - ## Navigating the Filesystem + You can move around directories using the `cd` command: **macOS / Linux** + ```bash cd /tmp # Go to /tmp cd ~ # Go to your home directory cd .. # Go up one directory level -```` +``` **Windows (PowerShell)** + ```powershell cd C:\Temp cd $HOME cd .. -```` +``` > **Tip** > > Use `pwd` (Linux/macOS) or `Get-Location` (Windows) to check your current directory. - > **Common mistake:** > > Forgetting that commands like `cd` are case-sensitive on Linux/macOS. - ## Creating Directories + To organize your files, create a directory using: **macOS / Linux** + ```bash mkdir myproject # Make a new directory called myproject -```` +``` **Windows (PowerShell)** + ```powershell New-Item -ItemType Directory -Name myproject -```` +``` > **Tip** > ->You can create nested directories with `mkdir -p myproject/subdir` on Linux/macOS. - +> You can create nested directories with `mkdir -p myproject/subdir` on Linux/macOS. > **Common mistake:** > > Trying to create a directory that already exists will fail unless using the `-p` flag. - ## Creating Files + Create an empty file inside a directory: **macOS / Linux** + ```bash touch myproject/hello.txt -```` +``` **Windows (PowerShell)** + ```powershell New-Item -ItemType File myproject/hello.txt -```` +``` > **Tip** > ->Files can be created in any directory you have write permissions for. - +> Files can be created in any directory you have write permissions for. > **Common mistake:** > > Forgetting to specify the directory and ending up creating the file in the wrong place. - ## Editing Files + You can open and edit files with a text editor of your choice: **macOS / Linux** + ```bash nano myproject/hello.txt -```` +``` **Windows (PowerShell)** + ```powershell notepad myproject/hello.txt -```` +``` Add the following line to the file: @@ -156,62 +200,64 @@ Hello from the command line! > **Tip** > ->Try a simple editor like nano or notepad first; later you can use VS Code for larger projects. - +> Try a simple editor like nano or notepad first; later you can use VS Code for larger projects. > **Common mistake:** > > Forgetting to save the file before exiting the editor. - ## Viewing File Contents + Check the contents of a file using these commands: **macOS / Linux** + ```bash cat myproject/hello.txt -```` +``` **Windows (PowerShell)** + ```powershell Get-Content myproject/hello.txt -```` +``` > **Tip** > ->Use these commands to quickly verify your edits. - +> Use these commands to quickly verify your edits. > **Common mistake:** > > Using `cat` on very large files can flood the terminal; use `less` instead. - ## Searching Within Files + Search for specific text inside a file: **macOS / Linux** + ```bash grep "Hello" myproject/hello.txt -```` +``` **Windows (PowerShell)** + ```powershell Select-String -Pattern "Hello" -Path myproject/hello.txt -```` +``` + > **Tip** > > Use search to verify that text exists or to debug issues in configuration files. - > **Common mistake:** > > Forgetting to quote search patterns with spaces, which can break the command. - ## Getting Help for a CLI Click-based CLIs support the `--help` option, which lists commands and options: + ``` mycli --help ``` From 1f325bbd543c6c4d40f6f3b844b5bf732a15d172 Mon Sep 17 00:00:00 2001 From: Venom Date: Sat, 20 Dec 2025 15:35:24 +0100 Subject: [PATCH 07/12] docs: modified the title for clarity. The section is about the different commands not interacting with a system, which sounds generic --- docs/intro_to_command_line_tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro_to_command_line_tutorial.md b/docs/intro_to_command_line_tutorial.md index 8e231ae44..54fb74066 100644 --- a/docs/intro_to_command_line_tutorial.md +++ b/docs/intro_to_command_line_tutorial.md @@ -45,7 +45,7 @@ By the end of this tutorial, you will be able to: - A computer with a shell (macOS / Linux / Windows). - A text editor you can run from the terminal (nano, vi, notepad, code, etc.). -## Understanding Your System +## Interacting with your command line Before using the command line, it's important to know which operating system and shell you are running. Different systems have slightly different commands, so this knowledge will help you follow tutorials and avoid errors. From f72e6648a3c447302b52e5d574c4ece367166cbd Mon Sep 17 00:00:00 2001 From: Venom Date: Sat, 20 Dec 2025 15:44:43 +0100 Subject: [PATCH 08/12] docs(fix): removed some of the extra comments here as somes goes beyond the scope of the tutorial. kept it simple and clean for users to see what command to run. --- docs/intro_to_command_line_tutorial.md | 236 +++++-------------------- 1 file changed, 44 insertions(+), 192 deletions(-) diff --git a/docs/intro_to_command_line_tutorial.md b/docs/intro_to_command_line_tutorial.md index 54fb74066..be373c98f 100644 --- a/docs/intro_to_command_line_tutorial.md +++ b/docs/intro_to_command_line_tutorial.md @@ -47,227 +47,79 @@ By the end of this tutorial, you will be able to: ## Interacting with your command line -Before using the command line, it's important to know which operating system and shell you are running. -Different systems have slightly different commands, so this knowledge will help you follow tutorials and avoid errors. +Before using the command line, it's helpful to know which operating system and shell you are running. Different systems have slightly different commands; the examples below are grouped by platform so you can copy the commands that match your environment. -**macOS / Linux** +### macOS / Linux ```bash -uname -a # Display OS version and system information -``` - -**Windows (PowerShell)** - -```powershell -Get-ComputerInfo | Select-Object WindowsVersion, OsName, OsBuildNumber -``` - -> **Tip** -> -> Knowing your OS helps you troubleshoot problems more effectively. - -> **Common mistake:** -> -> Trying to run a Linux command on Windows without an appropriate shell like WSL. - -## Files, Directories, and Paths - -Command-line tools interact with files and directories: - -- **File**: A piece of stored data (text, code, image, etc.). -- **Directory (folder)**: A container for files or other directories. -- **Path**: A reference to a file or directory location, either relative or absolute. - -**macOS / Linux** - -```bash -pwd # Print working directory -ls # List files and directories -``` - -**Windows (PowerShell)** - -```powershell -Get-Location -Get-ChildItem -``` - -> **Tip** -> -> Relative paths start from your current directory; absolute paths start from the root. - -> **Common mistake:** -> -> Confusing relative and absolute paths, which can cause “file not found” errors. - -## Navigating the Filesystem - -You can move around directories using the `cd` command: - -**macOS / Linux** +# Show OS/version information +uname -a -```bash -cd /tmp # Go to /tmp -cd ~ # Go to your home directory -cd .. # Go up one directory level -``` - -**Windows (PowerShell)** +# Print working directory and list files +pwd +ls -la -```powershell -cd C:\Temp -cd $HOME +# Move around the filesystem +cd /tmp +cd ~ cd .. -``` - -> **Tip** -> -> Use `pwd` (Linux/macOS) or `Get-Location` (Windows) to check your current directory. - -> **Common mistake:** -> -> Forgetting that commands like `cd` are case-sensitive on Linux/macOS. -## Creating Directories - -To organize your files, create a directory using: - -**macOS / Linux** - -```bash -mkdir myproject # Make a new directory called myproject -``` - -**Windows (PowerShell)** - -```powershell -New-Item -ItemType Directory -Name myproject -``` - -> **Tip** -> -> You can create nested directories with `mkdir -p myproject/subdir` on Linux/macOS. - -> **Common mistake:** -> -> Trying to create a directory that already exists will fail unless using the `-p` flag. - -## Creating Files - -Create an empty file inside a directory: - -**macOS / Linux** - -```bash +# Create a directory and an empty file +mkdir -p myproject touch myproject/hello.txt -``` - -**Windows (PowerShell)** - -```powershell -New-Item -ItemType File myproject/hello.txt -``` - -> **Tip** -> -> Files can be created in any directory you have write permissions for. - -> **Common mistake:** -> -> Forgetting to specify the directory and ending up creating the file in the wrong place. -## Editing Files - -You can open and edit files with a text editor of your choice: - -**macOS / Linux** - -```bash +# Edit the file (simple editor) nano myproject/hello.txt -``` - -**Windows (PowerShell)** - -```powershell -notepad myproject/hello.txt -``` - -Add the following line to the file: - -``` -Hello from the command line! -``` - -> **Tip** -> -> Try a simple editor like nano or notepad first; later you can use VS Code for larger projects. - -> **Common mistake:** -> -> Forgetting to save the file before exiting the editor. - -## Viewing File Contents +# What to put in the file +# Hello from the command line! -Check the contents of a file using these commands: -**macOS / Linux** - -```bash +# Print file contents cat myproject/hello.txt -``` -**Windows (PowerShell)** +# Search inside the file +grep "Hello" myproject/hello.txt -```powershell -Get-Content myproject/hello.txt +# Show a CLI's help message (mycli here refers to any command line program e.g git, python, etc.) +mycli --help +python -m mycli --help ``` -> **Tip** -> -> Use these commands to quickly verify your edits. +### Windows (cmd.exe) -> **Common mistake:** -> -> Using `cat` on very large files can flood the terminal; use `less` instead. +```bat +REM Show OS/version information +ver -## Searching Within Files +REM Current directory and list files +echo %CD% +dir -Search for specific text inside a file: - -**macOS / Linux** - -```bash -grep "Hello" myproject/hello.txt -``` - -**Windows (PowerShell)** - -```powershell -Select-String -Pattern "Hello" -Path myproject/hello.txt -``` +REM Move around +cd /d C:\Temp +cd /d %USERPROFILE% +cd .. -> **Tip** -> -> Use search to verify that text exists or to debug issues in configuration files. +REM Create directory and file +mkdir myproject +type nul > myproject\hello.txt -> **Common mistake:** -> -> Forgetting to quote search patterns with spaces, which can break the command. +REM Edit with notepad +notepad myproject\hello.txt -## Getting Help for a CLI +REM Print file contents +type myproject\hello.txt -Click-based CLIs support the `--help` option, which lists commands and options: +REM Search for Hello (findstr) +findstr "Hello" myproject\hello.txt -``` +REM Show help for a CLI (mycli here refers to any command line program e.g git, python, etc.) mycli --help -``` - -If the CLI is implemented as a Python module: - -``` python -m mycli --help ``` +Save and exit the editor, then verify with `cat` / `type` depending on your shell. + ## Further Reading - [SW Carpentry](https://swcarpentry.github.io/shell-novice/) From b99a8a902611757c1a64dfde2aa1387161e2353d Mon Sep 17 00:00:00 2001 From: Venom Date: Sat, 20 Dec 2025 15:46:21 +0100 Subject: [PATCH 09/12] docs(fix): added a summary section, quick reference section and a conclusion message --- docs/intro_to_command_line_tutorial.md | 44 +++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/docs/intro_to_command_line_tutorial.md b/docs/intro_to_command_line_tutorial.md index be373c98f..e0ace970f 100644 --- a/docs/intro_to_command_line_tutorial.md +++ b/docs/intro_to_command_line_tutorial.md @@ -118,7 +118,49 @@ mycli --help python -m mycli --help ``` -Save and exit the editor, then verify with `cat` / `type` depending on your shell. +## Short explanations (why these commands matter) + +- Operating system information helps you choose the right commands and troubleshoot issues. +- Directories (folders) contain files and other directories. Paths can be absolute (start at the filesystem root) or relative (start from your current directory). +- Moving around with `cd` changes your working directory; many commands operate relative to it. +- Creating and editing small files is how you try things quickly from the terminal without opening a full IDE. +- Grep-style searching is essential for finding text in logs, configs, or code. +- Most CLIs expose `--help` (or `-h`) which documents commands, options, and usage. + +## Quick reference (cheat sheet) + +macOS / Linux + +```bash +pwd # print working directory +ls -la # list files +cd # change directory +mkdir -p # make directory +touch # create empty file +nano # edit +cat # print contents +grep # search +mycli --help # CLI help (mycli here refers to any command line program e.g git, python, etc.) +``` + +Windows (cmd.exe) + +```bat +echo %CD% +dir +cd /d +mkdir +type nul > +notepad +type +findstr +mycli --help +``` + +## Conclusion + +Congratulations! You've completed the command line basics tutorial. +You now have the foundational skills to navigate and interact with your computer using the command line. And you are ready to explore Click-based CLIs and build your own! ## Further Reading From f35802c5517f2917be8ed5a17f5981764a957dd1 Mon Sep 17 00:00:00 2001 From: Venom Date: Sat, 20 Dec 2025 15:59:15 +0100 Subject: [PATCH 10/12] docs: added more precise links to cover the topics covered. As well as removing powershell links. And uses the myst format for links --- docs/intro_to_command_line_tutorial.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/intro_to_command_line_tutorial.md b/docs/intro_to_command_line_tutorial.md index e0ace970f..34631875b 100644 --- a/docs/intro_to_command_line_tutorial.md +++ b/docs/intro_to_command_line_tutorial.md @@ -162,9 +162,12 @@ mycli --help Congratulations! You've completed the command line basics tutorial. You now have the foundational skills to navigate and interact with your computer using the command line. And you are ready to explore Click-based CLIs and build your own! -## Further Reading +## Next steps and Further Reading -- [SW Carpentry](https://swcarpentry.github.io/shell-novice/) -- [Microsoft Powershell](https://learn.microsoft.com/powershell/) -- [Ubuntu](https://ubuntu.com/tutorials/command-line-for-beginners) -- [Python](https://docs.python.org/3/tutorial/venv.html) +These resources will take you deeper: + +- Shell basics tutorial: https://swcarpentry.github.io/shell-novice/ +- Bash manual: https://www.gnu.org/software/bash/manual/ +- Grep manual (GNU): https://www.gnu.org/software/grep/manual/grep.html +- Filesystem hierarchy (Linux): https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard +- Windows filesystem and paths: https://learn.microsoft.com/windows/win32/fileio/file-paths From bda02c62857c3e3e92f029f4420afdf38cefcb27 Mon Sep 17 00:00:00 2001 From: Venom Date: Sat, 20 Dec 2025 16:04:31 +0100 Subject: [PATCH 11/12] docs(rename): renamed the file from intro_to_command_line_tutorial to command-line-tutorial to keep the naming convention consistent as used in the docs folder --- ...tro_to_command_line_tutorial.md => command-line-tutorial.md} | 0 docs/index.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{intro_to_command_line_tutorial.md => command-line-tutorial.md} (100%) diff --git a/docs/intro_to_command_line_tutorial.md b/docs/command-line-tutorial.md similarity index 100% rename from docs/intro_to_command_line_tutorial.md rename to docs/command-line-tutorial.md diff --git a/docs/index.rst b/docs/index.rst index 578a285dd..6b3eb00c9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -71,7 +71,7 @@ Tutorials quickstart virtualenv - intro_to_command_line_tutorial + command-line-tutorial How to Guides --------------- From 5980c305fab88a01fbbc2656ae69532db1c10891 Mon Sep 17 00:00:00 2001 From: Venom Date: Wed, 21 Jan 2026 23:28:27 +0100 Subject: [PATCH 12/12] docs: fixed all the requested changes with regards to the docs command line tutorial --- docs/command-line-tutorial.md | 68 +++++++++++++++-------------------- 1 file changed, 28 insertions(+), 40 deletions(-) diff --git a/docs/command-line-tutorial.md b/docs/command-line-tutorial.md index 34631875b..67c8b45be 100644 --- a/docs/command-line-tutorial.md +++ b/docs/command-line-tutorial.md @@ -1,25 +1,20 @@ -# Command line basics — Introduction to command line interfaces (CLIs) +# Command line basics -This short, hands-on tutorial gives developers the minimal set of command-line skills needed to start using or building Click-based CLIs. -It is written for beginners who may have little or no command line experience. -All examples provide commands for both macOS/Linux (Bash) and Windows (cmd). +TThis tutorial shows the developer the basics of using the command line. It should take about 20 minutes to complete. ```{contents} :depth: 2 :local: ``` -First Let's understand what a command line interface is. - ## What is a Command Line Interface (CLI)? A Command Line Interface (CLI) is a text-based way to interact with your computer. -Instead of clicking icons or buttons, you type commands into a terminal or console window. -CLIs are powerful tools for developers and system administrators because they allow for automation, scripting, and remote access to systems. -Examples of popular CLIs include: +Instead of clicking icons or buttons, you type commands into a terminal. Some examples +of terminals include: -- **Bash** (Bourne Again SHell): Common on macOS and Linux systems. -- **cmd.exe**: The traditional command prompt on Windows. +- **Bash** (Bourne Again SHell): Common on macOS and Linux systems. +- **cmd.exe**: The traditional command prompt on Windows. ## How does it work? @@ -29,28 +24,17 @@ Users type commands into a CLI shell (e.g., Bash, cmd), which interprets and exe **Command Process:** The shell parses the command, identifying the action, options, and arguments. It locates the command in the system’s PATH and executes it. The system returns output (e.g., data, error messages) to the CLI. -## What you will learn - -By the end of this tutorial, you will be able to: - -- Identify your OS and shell -- See the difference between files and directories, and how paths work -- Move around the filesystem, create a directory and a file -- Edit the file and print its contents in the terminal -- Search inside a file (grep-style) -- View a CLI's help output - ## Prerequisites -- A computer with a shell (macOS / Linux / Windows). -- A text editor you can run from the terminal (nano, vi, notepad, code, etc.). +- A computer with a shell (macOS / Linux / Windows). +- A text editor you can run from the terminal (nano, vi, notepad, code, etc.). ## Interacting with your command line Before using the command line, it's helpful to know which operating system and shell you are running. Different systems have slightly different commands; the examples below are grouped by platform so you can copy the commands that match your environment. -### macOS / Linux - +````{tabs} +```{tab} macOS / Linux ```bash # Show OS/version information uname -a @@ -73,7 +57,6 @@ nano myproject/hello.txt # What to put in the file # Hello from the command line! - # Print file contents cat myproject/hello.txt @@ -83,10 +66,11 @@ grep "Hello" myproject/hello.txt # Show a CLI's help message (mycli here refers to any command line program e.g git, python, etc.) mycli --help python -m mycli --help -``` +```` -### Windows (cmd.exe) +```` +```{tab} Windows (cmd.exe) ```bat REM Show OS/version information ver @@ -116,16 +100,20 @@ findstr "Hello" myproject\hello.txt REM Show help for a CLI (mycli here refers to any command line program e.g git, python, etc.) mycli --help python -m mycli --help +```` + +``` + ``` ## Short explanations (why these commands matter) -- Operating system information helps you choose the right commands and troubleshoot issues. -- Directories (folders) contain files and other directories. Paths can be absolute (start at the filesystem root) or relative (start from your current directory). -- Moving around with `cd` changes your working directory; many commands operate relative to it. -- Creating and editing small files is how you try things quickly from the terminal without opening a full IDE. -- Grep-style searching is essential for finding text in logs, configs, or code. -- Most CLIs expose `--help` (or `-h`) which documents commands, options, and usage. +- Operating system information helps you choose the right commands and troubleshoot issues. +- Directories (folders) contain files and other directories. Paths can be absolute (start at the filesystem root) or relative (start from your current directory). +- Moving around with `cd` changes your working directory; many commands operate relative to it. +- Creating and editing small files is how you try things quickly from the terminal without opening a full IDE. +- Grep-style searching is essential for finding text in logs, configs, or code. +- Most CLIs expose `--help` (or `-h`) which documents commands, options, and usage. ## Quick reference (cheat sheet) @@ -166,8 +154,8 @@ You now have the foundational skills to navigate and interact with your computer These resources will take you deeper: -- Shell basics tutorial: https://swcarpentry.github.io/shell-novice/ -- Bash manual: https://www.gnu.org/software/bash/manual/ -- Grep manual (GNU): https://www.gnu.org/software/grep/manual/grep.html -- Filesystem hierarchy (Linux): https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard -- Windows filesystem and paths: https://learn.microsoft.com/windows/win32/fileio/file-paths +- Shell basics tutorial: https://swcarpentry.github.io/shell-novice/ +- Bash manual: https://www.gnu.org/software/bash/manual/ +- Grep manual (GNU): https://www.gnu.org/software/grep/manual/grep.html +- Filesystem hierarchy (Linux): https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard +- Windows filesystem and paths: https://learn.microsoft.com/windows/win32/fileio/file-paths