From 55966a541b15429012e02ec044aab8df5368bd44 Mon Sep 17 00:00:00 2001 From: Veritia Date: Thu, 27 Nov 2025 17:19:02 +0000 Subject: [PATCH 1/5] 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 0000000000..ed746aab85 --- /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 2/5] 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 3/5] 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 4/5] 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 a6bcd84166..e3eccfa891 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 5/5] Trigger Read the Docs rebuild