# zsh basics

> The shell in every WolOS terminal: history, Tab, suggestions, the colours of a command line, wildcards, pipes, saving output to a file, and your own settings.

Source: https://wolos.org/manual/zsh-basics

## What it is

zsh is the shell that reads what you type in a WolOS terminal. [What a terminal is](/manual/terminal) taught the parts of a command line; this page teaches what zsh adds on top so that typing commands is quick and forgiving: it remembers what you typed, finishes names, suggests whole commands, colours mistakes before you press Return, and lets you join small commands into bigger ones.

## Why WolOS does it this way

zsh runs the same commands as the shells of most servers and tutorials, so what you read elsewhere works here. WolOS sets it up for you: the history is large and shared between your terminal windows, Tab completion ignores capitals, the prompt shows where you are and whether the last command worked, and none of it needs a configuration file of your own. Your own settings go in one file that WolOS never touches, so an update never undoes them.

## How

### The prompt tells you three things

```
~/Documents/Recipes main ❯
```

The folder you are in (long paths are shortened to the last three folders), the branch name when the folder is a project kept in git, and the arrow. The arrow is in the accent colour when the last command worked and red when it failed.

### History: every command you typed

- **Up arrow** brings back the command before; press it again to go further back. If you typed the start of a command first, Up shows only earlier commands that start the same way: type `cd` and press Up to step through your earlier `cd` commands.
- History is shared: a command typed in one terminal window is in the history of the others too.
- The same command twice in a row is kept once. The last 50,000 commands are kept.
- A command that starts with a space is not kept at all. Use that for a line with a password in it.

> **Tip:** When you press Return on a command brought back with `!!` (the last command) or similar shortcuts, zsh first shows the full command and waits for a second Return, so you see what will run.

### Tab: finish names, list choices

Press **Tab** after the first letters of a command, a file or a folder. With one match, zsh fills it in. With several, the first Tab lists them and the second walks through the list with highlighted entries; Return picks one and Escape keeps what you typed. Shift+Tab walks back.

Tab is forgiving: capitals do not matter (`doc` finds `Documents`), and you can give the start of each part of a name (`D/R` finds `Documents/Recipes`). Tab also completes the options of many commands: type `ls --` and press Tab.

### Suggestions in grey

While you type, zsh shows in grey the rest of a command you typed before. Press **Right arrow** or **End** to take it, or just keep typing to ignore it.

### Colours before you press Return

As you type, the command turns green when zsh knows it and red when it does not, so `lss` is red before you run it. A file or folder that exists is underlined.

### Moving around a line

| Keys | What they do |
|---|---|
| Home, End | Start or end of the line |
| Ctrl+Left, Ctrl+Right (or Alt) | One word left or right |
| Ctrl+Backspace | Delete the word before the cursor |
| Ctrl+A, Ctrl+E | Start or end of the line (the same as Home and End) |
| Ctrl+U | Delete the whole line |
| Ctrl+C | Give up on this line (or stop the running command) |
| Ctrl+L | Clear the window |

### Go to a folder by its name

Type just the name of a folder and press Return: zsh goes there, as if you had typed `cd` in front. `Documents` takes you to Documents, `..` one folder up.

### Short forms WolOS adds

| Type | Means |
|---|---|
| `ll` | `ls -lh`: one line per file, with sizes in KB, MB and GB |
| `la` | The same, with hidden files |

### Wildcards: many files at once

`*` stands for any letters, `?` for exactly one. zsh replaces the pattern with every matching name before the command runs.

| Type | Means |
|---|---|
| `ls *.jpg` | Every file whose name ends in .jpg |
| `ls IMG_20?.jpg` | IMG_200.jpg to IMG_209.jpg |
| `cp *.pdf ~/Documents` | Copy every PDF here into Documents |

> **Careful:** A wildcard makes a command act on many files at once. Run `ls` with the same pattern first to see which files it means, especially before `rm` (remove), which deletes without the Trash.

### Joining commands

| You write | What happens |
|---|---|
| `ls ~/Pictures \| wc -l` | The bar `\|` (a *pipe*) hands the output of the first command to the second: `wc -l` counts the lines, so this counts your pictures. |
| `ls ~/Documents > list.txt` | `>` saves the output to a file instead of showing it (and replaces the file if it exists). `>>` adds to the end instead. |
| `cd Documents && ls` | `&&` runs the second command only if the first worked. |
| `# a note` | Anything after `#` is a comment and is not run. |

### Quotes for names with spaces

A space separates arguments, so a name with a space needs quotes: `cd "Holiday photos"` or `cd 'Holiday photos'`. Tab adds the right marks for you. Single quotes keep everything as typed; inside double quotes `$HOME` and friends are replaced by their value.

### Your own settings

Your settings go in the file `.zshrc` in your home folder (a hidden file). WolOS's own settings are read first and yours afterwards, so a line of yours wins. Updates never touch your file. Open it with a text editor, add for example

```
alias photos='cd ~/Pictures'
```

save it, and open a new terminal: typing `photos` now takes you to your pictures.

### More in the Console module

System Settings > Modules > **Console** adds tools many people like: a richer prompt in the colours of your theme, a searchable history on Ctrl+R, a file picker on Ctrl+T, `z` to jump to folders you visit often, and a colourful `ls`. Each one turns itself on once it is installed.

### Another shell for new terminal windows

System Settings > General > **Shell in the terminal** chooses the shell new terminal windows open in: bash, fish, nu or PowerShell, when installed. Your account itself keeps zsh, because the desktop and other programs expect it. See [PowerShell basics](/manual/powershell-basics).

## A worked example

Alice has 40 photos named `IMG_…jpg` in Downloads and wants them in a new folder. She types `cd Dow`, Tab, Return (zsh completes `Downloads/`). `ls *.jpg | wc -l` prints `40`. `mkdir ~/Pictures/Garden` makes the new folder, and `mv *.jpg ~/Pictures/Garden` moves them all. `ls ~/Pictures/Garden | wc -l` prints `40` again. Pressing Up three times brings back the `ls` line in case she needs it once more.

## If something goes wrong

| What you see | What to do |
|---|---|
| `zsh: no matches found: *.jpg` | No file matches the pattern where you are. Check the folder with `pwd` and `ls`. |
| `zsh: command not found: …` | Check the spelling (the red colour warned you). If it is right, the program is not installed. |
| A line starting with `quote>` or `dquote>` | An opening quote mark has no closing one. Type it and press Return, or Ctrl+C to start again. |
| Your alias does nothing | Open a new terminal window: `.zshrc` is read when a terminal starts. |
| The terminal behaves strangely after editing `.zshrc` | Rename the file (in Files, show hidden files with Ctrl+H), open a new terminal: WolOS's own settings are back. |