foxshell/README.md

# FoxShell

A powerful and user-friendly configuration for Zsh that works out of the box. FoxShell combines the best
Zsh plugins into a coherent whole that feels like a finished product rather than a DIY starter kit.

If you want a great shell that just works, this project is for you.

## Table of contents

* 1. [Features](#features)
* 2. [Installation](#installation)
* 3. [Usage](#usage)
  * 3.1. [Accepting autosuggestions](#accepting-autosuggestions)
  * 3.2. [Completing commands](#completing-commands)
  * 3.3. [Searching command history](#searching-command-history)
  * 3.4. [Interactive search with `fzf`](#interactive-search-with-fzf)
  * 3.5. [SSH](#ssh)
* 4. [Customization](#customization)
  * 4.1. [Customizing prompt](#customizing-prompt)
  * 4.2. [Customizing appearance](#customizing-appearance)
  * 4.3. [Additional Zsh startup files](#additional-zsh-startup-files)
* 5. [Updating](#updating)
* 6. [Uninstalling](#uninstalling)
* 7. [Advanced configuration tips](#advanced-configuration-tips)

## Features

- Powerful POSIX-based shell preconfigured to work great out of the box.
- Easy-to-use installation wizard. Does not require `git`, `zsh` or `sudo`.
- [Syntax highlighting](https://github.com/zsh-users/zsh-syntax-highlighting) for the command line.
- [Autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) for commands based on command
  history.
- [Command prompt](https://github.com/romkatv/powerlevel10k) configurable through a builtin
  configuration wizard.
- Command completions and history searchable with [fzf](https://github.com/junegunn/fzf).
- Super fast. No lag when you open a new tab in the terminal or run a command.
- The complete shell environment can be automatically teleported to the remote host when connecting
  over `ssh`. This does not require `git`, `zsh` or `sudo` on the remote host.
- Command history can be shared across different hosts. For example, history from `ssh foo`
  can be made available within `ssh bar` and/or on the local machine.

## Installation

Run this command in bash, zsh, or sh:

```shell
if command -v curl >/dev/null 2>&1; then
  sh -c "$(curl -fsSL https://git.foxdale.tech/Arctic/foxshell/raw/branch/main/install)"
else
  sh -c "$(wget -O- https://git.foxdale.tech/Arctic/foxshell/raw/branch/main/install)"
fi
```

The installer backs up the existing Zsh startup files, creates new ones, installs everything
necessary for FoxShell, starts a new shell, and configures it as login shell. It asks for
confirmation on every step so that you are always in control. Installation requires `curl` or
`wget`. It does not require `git`, `zsh`, `sudo` or anything else.

## Usage

If you've used Zsh, Bash or Fish before, FoxShell should feel familiar. For the most part
everything works as you would expect.

### Accepting autosuggestions

All key bindings that move the cursor can accept *command autosuggestions*. For example, moving the
cursor one word to the right will accept that word from the autosuggestion. The whole autosuggestion
can be accepted without moving the cursor with <kbd>Alt+M</kbd>/<kbd>Option+M</kbd>.

Autosuggestions in FoxShell are provided by [zsh-autosuggestions](
  https://github.com/zsh-users/zsh-autosuggestions). See its homepage for more information.

### Completing commands

When completing with <kbd>Tab</kbd>, suggestions come from *completion functions*. For most
commands completion functions are provided by Zsh proper. Additional completion functions are
contributed by [zsh-completions](https://github.com/zsh-users/zsh-completions). See its homepage
for the list of commands it supports.

Ambiguous completions automatically start [fzf](#interactive-search-with-fzf). Accept the desired
completion with <kbd>Enter</kbd>. You can also select more than one completion with
<kbd>Ctrl+Space</kbd> or all of them with <kbd>Ctrl+A</kbd>.

### Searching command history

<kbd>Up</kbd> and <kbd>Down</kbd> keys fetch commands from history that contain what you've already
typed on the command line. For example, if you press <kbd>Up</kbd> after typing `grep`, you'll see
the last executed command that contains `grep`.

<kbd>Ctrl+R</kbd> starts [fzf](#interactive-search-with-fzf) to search over history.

### Interactive search with `fzf`

Several UI elements in FoxShell use [fzf](https://github.com/junegunn/fzf) to quickly select
an item from a potentially large list of candidates. You can type multiple search terms delimited by
spaces. For example:

```text
^music .mp3$ sbtrkt !fire
```

| Token     | Match type        | Description                          |
| --------- | ----------------- | ------------------------------------ |
| `wild`    | substring         | Items with the substring `wild`      |
| `^music`  | prefix            | Items that start with `music`        |
| `.mp3$`   | suffix            | Items that end with `.mp3`           |
| `!wild`   | inverse substring | Items without the substring `wild`   |
| `!^music` | inverse prefix    | Items that do not start with `music` |
| `!.mp3$`  | inverse suffix    | Items that do not end with `.mp3`    |

A single bar (`|`) acts as an OR operator. For example, the following query matches entries that
start with `core` and end with either `go`, `rb`, or `py`.

```text
^core go$ | rb$ | py$
```

See [fzf](https://github.com/junegunn/fzf) homepage for more information.

### SSH

When you connect to a remote host over SSH, your local FoxShell environment can be teleported
over to it. The first login to a remote host may take some time. After that it's as fast as normal
`ssh`.

Search for "ssh" in your `~/.zshrc` for information on how to enable and configure SSH
teleportation.

## Customization

You can (and should) edit `~/.zshrc` to customize your shell. It's a very good idea to read through
the whole file to see which customization options are in there and to flip some of them to your
liking.

When adding your customizations, put them next to the existing lines that do similar things. The
default `~/.zshrc` contains the following types of customizations that should serve as examples:

- Export environment variables.
- Extend `PATH`.
- Define aliases.
- Add flags to existing aliases.
- Define functions.
- Source additional local files.
- Load Oh My Zsh plugins.
- Clone and load external Zsh plugins.
- Set shell options.
- Autoload functions.
- Change key bindings.

### Customizing prompt

Prompt in FoxShell is provided by [Powerlevel10k](https://github.com/romkatv/powerlevel10k).
Run `p10k configure` to access its interactive configuration wizard. Further customization can be
done by editing `~/.p10k*.zsh` files. There can be more than one configuration file to account for
terminals with limited capabilities. Most users will ever only see `~/.p10k.zsh`. When in doubt,
consult `$POWERLEVEL9K_CONFIG_FILE`. This parameter is set by FoxShell and it always points
to the Powerlevel10k config file currently in use.

### Customizing appearance

FoxShell uses a dark theme by default. You can customize colors and appearance by editing the
configuration files or using the built-in configuration wizard.

### Additional Zsh startup files

FoxShell sources additional files if they exist:

- `~/.env.zsh` - Environment variables and other shell configuration
- `~/.zshrc.local` - Additional personal configuration

## Updating

Run `foxshell update` to update FoxShell and all its components.

## Uninstalling

To uninstall FoxShell:

```shell
rm -rf -- "${XDG_CACHE_HOME:-$HOME/.cache}/foxshell"
```

Then restore your original zsh configuration files if you have backups.

## Advanced configuration tips

FoxShell is designed to be highly configurable. Here are some advanced tips:

- Use `zstyle` commands to configure various aspects of the shell
- Add custom key bindings with `foxshell bindkey`
- Install additional plugins with `foxshell install`
- Use `foxshell source` to source additional files
- Use `foxshell load` to load plugins

For more information, see the configuration files in `~/.zshrc`.