Refactor zsh4humans to foxshell - complete rebrand with new repository integration
This commit is contained in:
parent
0610f4aeab
commit
2b6ea4f5a3
7 changed files with 908 additions and 51 deletions
195
README.md
Normal file
195
README.md
Normal file
|
|
@ -0,0 +1,195 @@
|
|||
# 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`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue