Skip to content

Commit

Permalink
a few edits throughout cli chapter, see #51
Browse files Browse the repository at this point in the history
  • Loading branch information
@lnnrtwttkhn
lnnrtwttkhn committed Oct 23, 2023
1 parent 25b3888 commit e3edfc3
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 79 deletions.
165 changes: 90 additions & 75 deletions chapters/command-line.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,13 @@ execute:
title-block-style: none
author: ""
categories: [beginner, basics, command line]
description: |
abstract: |
In this session, we will explore the concept of the command line and discover some commands that work well alongside git.
abstract-title: "Overview"
---

::: {.callout-tip}

In this lesson, we will introduce the command line as a general concept and learn a few commands that are complimentary to git

{{< fa clock >}} Teaching: 30 min | Exercises: 15 min
:::

:::: {.columns}
Expand All @@ -37,49 +35,27 @@ In this lesson, we will introduce the command line as a general concept and lear
- Explain how the shell relates to the keyboard, the screen, the operating system, and users’ programs.
- Explain when and why command-line interfaces should be used instead of graphical interfaces.
- Understand how to form file paths and navigate directories
- Understand the difference between absolute and relative paths
- Understand how arguments and flags are used to modify command line commands
- Understand the concept of wild cards (`*`)

:::

::::

## Acknowledgements

```{r}
#| eval: true
#| echo: false
#| message: false
#| warning: false
#| output: asis
bibtexkeys = c("mcbain2019", "capes2023", "millman2018", "milligan2014")
knitr::kable(ref_table(bibtexkeys), format = "markdown")
```

## Cheatsheet

```{r}
#| eval: true
#| echo: false
#| message: false
#| warning: false
knitr::kable(table_cheatsheet(name = "cli"), format = "markdown")
```

## Prerequisites

If you have stored files on a computer and are familiar with terms such as "file," "directory," or "folder," you are adequately prepared for this lesson.

## Introduction

This will only teach you enough to be able to use git from the command line.
### Prerequisites

### Why using Git from the command line
If you have stored files on a computer and you are familiar with terms such as "file," "directory," or "folder," you are adequately prepared for this lesson.
The goal of this chapter is to teach you enough to be able to use Git from the command line.

git is fundamentally a command line tool.
This is why comfort with the command line is essential for learning git.
### Why using Git from the command line?

#### General advantages of the command line
Git is fundamentally a command-line tool.
This is why comfort with the command line is essential for learning Git.

### General advantages of the command line

1. **Longevity:** The command line has stood the test of time, remaining relevant and widely used even as new technologies emerge.
1. **Power:** The command line is a robust and powerful tool, enabling users to accomplish intricate tasks efficiently.
Expand All @@ -92,10 +68,10 @@ Platforms like [Stack Overflow](https://stackoverflow.com/questions/tagged/git)

## Terminology

The terms "shell", "command line", "command line interface (CLI)", and "Terminal" are used interchangeably and basically refer to the same thing: a simple window with a dark background and light text, showing a prompt and a blinking cursor.
The terms "shell", "command line", "command-line interface (CLI)", and "terminal" are used interchangeably and generally refer to the same thing: a simple window with a dark background and light text, showing a prompt and a blinking cursor.
In movies, when people hack into computers, they often type rapidly in this window.

The **"command line interface (CLI)"** is a text-based way to interact with computer programs.
The **"command-line interface (CLI)"** is a text-based way to interact with computer programs.
Most people primarily use a Graphical User Interface (GUI) to work with their programs, but historically, text-based interfaces were more common.
Often, the GUI can only access a limited set of features available through the CLI and some programs don't even have a GUI and can only be used through the command line.

Expand All @@ -106,23 +82,23 @@ The terminal program creates the window with the dark background, light text, an
A **"shell"** is a program that provides the command line to your operating system.
It allows you to perform various tasks that your operating system offers, such as managing files, running and stopping programs, and changing system settings, all through text commands.
When you "open a terminal", the program initially communicating with the terminal is a shell.
There are multiple shell options available for different operating systems, with the most popular one being the "Bourne Again Shell" or "bash".
There are multiple shell options available for different operating systems, with the most popular one being the "Bourne Again Shell" or "Bash".

## Find the command line
## Finding the command line

::: {.panel-tabset}

## {{< fa brands apple >}} MacOS

On a Mac computer running macOS Mojave or earlier versions, the default Unix Shell is Bash.
However, for a Mac computer operating on macOS Catalina or later releases, the default Unix Shell is Zsh.
You can access your default shell through the Terminal program located within the Utilities folder.
You can access your default shell through the Terminal program located within the Utilities folder:

- In the Finder, go to `Applications` > `Utilities` > `Terminal.app`.
- In the Finder, select the `Go` menu > `Utilities` > `Terminal.app`.
- Activate the Mac `Spotlight` search function, type `Terminal` in the search bar, and press the `Return` key.

To verify if your machine is configured to use a shell other than Bash, you can type "echo $SHELL" in your Terminal window.
To verify if your machine is configured to use a shell other than Bash, you can type `echo $SHELL` in your Terminal window.
If your machine is configured to use a shell other than Bash, you can switch to Bash by opening a terminal and typing `bash`.

## {{< fa brands microsoft >}} Windows
Expand All @@ -142,7 +118,7 @@ TBA

:::

## Open command line
## Opening the command line

When you open the shell, you'll see a prompt that tells you the shell is ready for input.
Your terminal interface will usually show a message similar to the following prompt:
Expand All @@ -152,11 +128,11 @@ $
```

In the shell, the prompt is usually represented by the symbol `$` but it can be different sometimes.
In our lesson examples, we'll use `$` as the prompt.
The important thing to remember is **not to type the prompt itself when entering commands**.
Only type the command that comes after the prompt.
In our examples, we'll use `$` as the prompt.
The important thing to remember is **to not type the prompt, `$`, itself when entering commands**.
Only type the command that comes after the `$` prompt.
For this reason, we remove the `$` prompt from all code examples.
Also, remember to press the `Enter` key after typing a command to make it work.
Also, remember to press the `Enter` key after typing a command to execute it.

After the prompt, you'll see a text cursor that shows where you can type.
The cursor can be a flashing or solid block, or it can be an underscore or a pipe symbol.
Expand All @@ -182,7 +158,7 @@ pwd
```

<details>
<summary>Click here to see an example output.</summary>
<summary>{{< fa eye >}} Click here to see the output of this command executed in the project directory of this guide.</summary>
```{bash}
#| eval: true
#| echo: false
Expand All @@ -203,32 +179,34 @@ pws: command not found

### Moving between folders

The `cd` command is used to change the current working directory (or "move" to a different directory).
To use it, type `cd` followed by an argument, which is the path of the folder you want to navigate to.
The path can be either "absolute" or "relative".
The `cd` command is used to change the current working directory (or "move" to a different directory in your file system).
To use it, type `cd` followed by an argument, which is the path of the folder you want to navigate to.
The path can be either *absolute* or *relative*.

For example, if your current working directory is the user's home directory (`/home/wittkuhn`), you can switch to the `Downloads` folder by using either an absolute or relative path with the `cd` command:
For example, if you are on macOS and your current working directory is your home directory (for example, `/Users/wittkuhn`), you can switch to the `/Downloads` folder by using either an absolute or relative path with the `cd` command:

```{bash, filename="Absolute path"}
wittkuhn@lip-osx-005509:~$ cd /home/wittkuhn/Downloads
wittkuhn@lip-osx-005509:~/Downloads$
wittkuhn@lip-osx-005509:~$ cd /Users/wittkuhn/Downloads
wittkuhn@lip-osx-005509:~/Downloads$ pwd
/Users/wittkuhn/Downloads
```

```{bash, filename="Relative path"}
wittkuhn@lip-osx-005509:~$ cd Downloads
wittkuhn@lip-osx-005509:~/Downloads$
wittkuhn@lip-osx-005509:~/Downloads$ pwd
/Users/wittkuhn/Downloads
```

You may notice that the prompt has been updated to show the new working directory.
If a path starts with a forward slash (`/`), it is considered an absolute path.
Paths that do not start with a forward slash are considered relative to the current working directory.
If a path starts with a forward slash (`/`), it is considered an *absolute* path.
Paths that do not start with a forward slash are considered *relative* to the current working directory.

### Taking shortcuts

#### Tilde: `~`

The tilde symbol (`~`) provides a convenient and abbreviated way to refer to the user's home directory, enabling us to easily construct paths relative to that directory.
To quickly change the current working directory to our user's home directory anywhere on our file system, we can use `cd ~` which will transport us back to our user's home directory.
To quickly change the current working directory to your user's home directory anywhere on your file system, we can use `cd ~` which will transport us back to the user's home directory.

```{bash}
wittkuhn@lip-osx-005509:~/Downloads$ cd ~
Expand All @@ -245,7 +223,7 @@ wittkuhn@lip-osx-005509:~$ cd .
wittkuhn@lip-osx-005509:~$
```

In turn, the two commands are equivalent:
In turn, these two commands are equivalent:

```{bash}
wittkuhn@lip-osx-005509:~$ cd ./Downloads
Expand Down Expand Up @@ -276,6 +254,24 @@ wittkuhn@lip-osx-005509:~/Documents$ pwd # <4>
1. Move sideways to the `Documents` folder.
1. Display the current working directory.

::: {.callout-tip title='What are "parent" and "child" directories?' collapse="true"}
In the context of file systems, a "parent directory" and a "child directory" describe the relationship between directories (or folders).

- **Parent Directory:** This is the directory that is "higher up" in the directory hierarchy and contains one or more "child directories."
- **Child Directory:** A child directory is located "inside" or "below" a parent directory.
It is contained within the parent directory and is considered subordinate to it, much like a child in a family is part of the larger family unit.

```{bash}
parent $ tree
.
├── child1
└── child2
3 directories
```

:::

## List files and folders

The `ls` command is used to list the files and folders in a specified directory or the current working directory.
Expand All @@ -285,10 +281,8 @@ If you run this command, you will see the contents of your current working direc
ls
```

For example, when the current working directory is the project directory of this book, `ls` will list the contents of the project directory.

<details>
<summary>Click here to view the output.</summary>
<summary>{{< fa eye >}} Click here to see the output of this command executed in the project directory of this guide.</summary>
```{bash}
#| eval: true
#| echo: false
Expand All @@ -309,7 +303,7 @@ ls chapters
```

<details>
<summary>Click here to view the output.</summary>
<summary>{{< fa eye >}} Click here to see the output of this command executed in the project directory of this guide.</summary>
```{bash}
#| eval: true
#| echo: false
Expand All @@ -330,7 +324,7 @@ ls -a
```

<details>
<summary>Click here to view the output.</summary>
<summary>{{< fa eye >}} Click here to see the output of this command executed in the `/chapters` directory of this guide.</summary>
```{bash}
#| eval: true
#| echo: false
Expand All @@ -354,7 +348,7 @@ Flags are optional and are used to customize the behavior of the command.
#### What is an argument?

An argument is the actual input or information that is passed to a command to perform a specific action.
It can be a value, a filename, a directory path, or any other data required by the command to complete its task.
It can be a value, a file name, a directory path, or any other data required by the command to complete its task.
Arguments are often positioned after the command and any flags, and they can be mandatory or optional depending on the command's requirements.

#### Multiple single-letter flags
Expand All @@ -367,7 +361,7 @@ ls -alh
```

<details>
<summary>Click here to view the output.</summary>
<summary>{{< fa eye >}} Click here to see the output of this command executed in the project directory of this guide.</summary>
```{bash}
#| eval: true
#| echo: false
Expand All @@ -387,7 +381,7 @@ The command line offers commands for creating, moving, and deleting folders and

### Creating a folder

Let's use the command line to create a project folder as an example:
Let's use the command line to create a new project folder as an example:
To make a directory, we'll use the `mkdir` command.
The path of the directory we want to create is given as an argument to the command.
If we want to create a directory in the current folder, we just need to use its name, as the path is assumed to be relative.
Expand All @@ -396,7 +390,7 @@ If we want to create a directory in the current folder, we just need to use its
mkdir my-project
```

Make sure the project folder is present by using the `ls` command, and then enter into it by using the `cd` command.
Make sure the project folder is present by using the `ls` command, and then move into it by using the `cd` command.

```{bash}
ls
Expand Down Expand Up @@ -449,14 +443,14 @@ mv scripts docs

Now, let's learn how to use wildcards to perform actions on multiple files or folders at the same time.
A wildcard is denoted by the symbol `*`, and it helps us select file system arguments that match certain patterns.
For example, suppose we wish to display a list of all the data files in the current directory:
For example, suppose we wish to display a list of all files of a certain file type (here, all files with the `.yml` file extension) in the current directory:

```{bash}
ls -alh *.yml
```

<details>
<summary>Click here to see the output of this command executed in the project directory of this guide.</summary>
<summary>{{< fa eye >}} Click here to see the output of this command executed in the project directory of this guide.</summary>
```{bash}
#| eval: true
#| echo: false
Expand All @@ -466,15 +460,14 @@ ls -alh *.yml
</details>

By using the wildcard `*`, we can generate a list of all files ending with `.yml`.

Similarly, we can apply the wildcard at the end of a path to match items starting with a specific letter, such as folders beginning with `i`:

```{bash}
ls -alh i*
```

<details>
<summary>Click here to see the output of this command executed in the project directory of this guide.</summary>
<summary>{{< fa eye >}} Click here to see the output of this command executed in the project directory of this guide.</summary>
```{bash}
#| eval: true
#| echo: false
Expand Down Expand Up @@ -505,9 +498,31 @@ In this lesson, we have achieved the following:
1. Witnessed the functionality of wildcards.
1. Acquired familiarity with several essential shell commands.

## Further reading

It's important to note that what we covered here only scratches the surface of what can be accomplished using the shell.
The primary aim was to provide useful concepts related to Git.
If you're interested in delving deeper, you may find a more comprehensive introduction at the following resource: [http://swcarpentry.github.io/shell-novice/].
The primary aim was to provide useful concepts that help when learning Git.
If you're interested in delving deeper, you may find a more comprehensive introduction at one of the following resource.

## Acknowledgements & further reading

We would like to express our gratitude to the following resources, which have been essential in shaping this chapter.
We recommend these references for further reading:

```{r}
#| eval: true
#| echo: false
#| message: false
#| warning: false
#| output: asis
bibtexkeys = c("mcbain2019", "capes2023", "millman2018", "milligan2014")
knitr::kable(ref_table(bibtexkeys), format = "markdown")
```

## Cheatsheet

```{r}
#| eval: true
#| echo: false
#| message: false
#| warning: false
knitr::kable(table_cheatsheet(name = "cli"), format = "markdown")
```
6 changes: 2 additions & 4 deletions cheatsheet.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,12 @@
"ls -a": "List all files (including hidden files) in the current working directory",
"ls -alh": "List all files in a long format that is easy to read for humans",
"mkdir <FOLDER>": "Create a new folder, called `<FOLDER>`",
"mkdir <FOLDER1> <FOLDER3>": "Create two separate folders",
"mkdir <FOLDER1> <FOLDER2>": "Create two separate folders, called <FOLDER1> and <FOLDER2>",
"touch <FILE>": "Create a new empty file, called `<FILE>`",
"mv FILE.txt <FOLDER>": "Move `FILE.txt` into `<FOLDER>`",
"mv <FOLDER_OLD> <FOLDER_NEW>": "Rename `<FOLDER_OLD>` to `<FOLDER_NEW>`",
"ls -alh *.csv": "Use a wildcard to list all `.csv` files",
"rm -r <FOLDER>": "Remove the folder `<FOLDER>`",
"ls": "List files and folders in the current working directory",
"ls <DIRECTORY>": "List files and folders in DIRECTORY"
"rm -r <FOLDER>": "Remove the folder `<FOLDER>`"
},
"config": {
"git config": "Overview of config commands",
Expand Down

0 comments on commit e3edfc3

Please sign in to comment.