Skip to content

Commit

Permalink
docs: revamp README to redirect towards mkdocs
Browse files Browse the repository at this point in the history
  • Loading branch information
@edouard-lopez
edouard-lopez committed Jan 23, 2024
1 parent e9eef44 commit ad66c8a
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 118 deletions.
138 changes: 28 additions & 110 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,7 @@

</div>

> ##### :arrow_up: Hey! Want to migrate from v3.x to v4.x? Check our [**migration guide**](https://github.com/pure-fish/pure/releases/tag/v4.0.0), done with ❤️
# pure
# pure `❯❮❯`

> Pretty, minimal and fast Fish 🐟 prompt, ported from [`zsh`](https://github.com/sindresorhus/pure).
Expand All @@ -17,25 +15,16 @@
<a href="https://camo.githubusercontent.com/5934e8c1d3b5f9218d05d5e1741e23963a7803d6098236d36e586336a6c6a5b7/68747470733a2f2f692e696d6775722e636f6d2f714a646f6e716f2e706e67" target=blank><img width=440 src=https://camo.githubusercontent.com/5934e8c1d3b5f9218d05d5e1741e23963a7803d6098236d36e586336a6c6a5b7/68747470733a2f2f692e696d6775722e636f6d2f714a646f6e716f2e706e67 alt="Pure with light colorscheme"></a>
</div>

## :rocket: Install

**:warning: requirements**: fish `≥3.x`
## Documentation

### [Fisher](https://github.com/jorgebucaran/fisher)
:sparkles: Check-out our [brand-new documentation][doc] for configurations, features and colours as well as contributing guide.

```shell
fisher install pure-fish/pure
```

### Manually
## :rocket: Install

Via [cURL](https://curl.haxx.se):
**:warning: requirements**: fish `≥3.x`, [fisher](https://github.com/jorgebucaran/fisher):

```shell
# Download the installer to `/tmp`
curl git.io/pure-fish --output /tmp/pure_installer.fish --location --silent
# Source and trigger the installer
source /tmp/pure_installer.fish; and install_pure
fisher install pure-fish/pure
```

## Features
Expand Down Expand Up @@ -68,115 +57,44 @@ Fully **customizable** (colors, symbols and features):
- Shorten _current folder_ component in prompt and window title 🏴;
- Truncate _current folder_ component in prompt and window title 🏴;

🏴: Enabled or disabled via a [feature flag](#-features-flags).
🏴: Enabled or disabled via a [feature flag][features].

## :paintbrush: Configuration
## Configuration

You can tweak `pure` behavior and color by changing [universal variables](https://fishshell.com/docs/current/tutorial.html#tut_universal) either directly in the terminal or in your `config.fish`, _e.g._:
See [How to configure pure prompt?][configure]

```shell
set --universal pure_show_system_time true
set --universal pure_color_system_time pure_color_mute
```
## Features' Flags

See [Features and their respective options][features].

## :heart: Contribute

### Prompt Symbol

| Option | Default | Description |
| :------------------------------------- | :------ | :--------------------------------------------------------------------------- |
| **`pure_symbol_container_prefix`** | | Prefix when being inside a container ([to customize][to-set]) |
| **`pure_symbol_git_dirty`** | `*` | Repository is Dirty (uncommitted/untracked changes). |
| **`pure_symbol_git_stash`** | `≡` | Repository git stash status. |
| **`pure_symbol_git_unpulled_commits`** | `⇣` | Branch is behind upstream (commits to pull). |
| **`pure_symbol_git_unpushed_commits`** | `⇡` | Branch is ahead upstream (commits to push). |
| **`pure_symbol_k8s_prefix`** | `☸` | Prefix when being connected to Kubernetes/K8s |
| **`pure_symbol_prefix_root_prompt`** | `#` | Prefix prompt when logged in as `root`. |
| **`pure_symbol_prompt`** | `❯` | Prompt symbol. |
| **`pure_symbol_reverse_prompt`** | `❮` | VI non-insert mode symbol. |
| **`pure_symbol_ssh_prefix`** | | Prefix when being connected to SSH session (default: [undefined][to-set]) |
| **`pure_symbol_title_bar_separator`** | `-` | Separator in terminal's windows title. |
| **`pure_symbol_virtualenv_prefix`** | | Prefix when a Python virtual env is activated (default: [undefined][to-set]) |

> :information_source: Need [safer `git` symbols](https://github.com/sindresorhus/pure/wiki/Customizations,-hacks-and-tweaks#safer-symbols)?
### 🔌 Features' Flags

| Option | Default | Description |
| :------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`pure_begin_prompt_with_current_directory`** | `true` | `true`: _`pwd` `git`, `SSH`, duration_.<br/>`false`: _`SSH` `pwd` `git`, duration_. |
| **`pure_check_for_new_release`** | `false` | `true`: check repo for new release (on every shell start) |
| **`pure_enable_container_detection`** | `true` | `false`: Do not check if run in container (e.g. `docker`, `podman`, `LXC`/`LXD`, etc.).<br/>:warning: Detection is a bit [tricky across OSes][container-detection]. |
| **`pure_enable_git`** | `true` | Show info about Git repository. |
| **`pure_enable_k8s`** | `false` | `true`: shows `kubernetes` context and namespace. |
| **`pure_enable_single_line_prompt`** | `false` | `true`: Compact prompt as a single line |
| **`pure_enable_virtualenv`** | `true` | Show virtual env name (based on `VIRTUAL_ENV` or `CONDA_DEFAULT_ENV`). |
| **`pure_reverse_prompt_symbol_in_vimode`** | `true` | `true`: `❮` indicate a non-insert mode.<br/>`false`: indicate vi mode with `[I]`, `[N]`, `[V]`. |
| **`pure_separate_prompt_on_error`** | `false` | Show last command [exit code as a separate character][exit-code]. |
| **`pure_shorten_prompt_current_directory_length`** | `0` | Shorten every prompt path component but the last to X characters (0 do not shorten) |
| **`pure_shorten_window_title_current_directory_length`** | `0` | Shorten every window title path component but the last to X characters (0 do not shorten) |
| **`pure_show_jobs`** | `false` | Show Number of running jobs |
| **`pure_show_prefix_root_prompt`** | `false` | `true`: shows prompt prefix when logged in as `root`. |
| **`pure_show_subsecond_command_duration`** | `false` | Show subsecond (ex. 1.5s) in command duration. |
| **`pure_show_system_time`** | `false` | `true`: shows system time before the prompt symbol (as `%H:%M:%S`). |
| **`pure_threshold_command_duration`** | `5` | Show command duration when above this value (seconds). |
| **`pure_truncate_prompt_current_directory_keeps`** | `0` | Truncate working directory path in prompt, but keeps the last to `n` components (`0` full path in current directory) |
| **`pure_truncate_window_title_current_directory_keeps`** | `0` | Truncate working directory path in window title, but keeps the last to `n` components (`0` full path in window title) |

### 🎨 Colours

> :information_source: See [`set_color`][fish-set-color] documentation for full possibilities.
> :warning: The absence of `$` sign is expected in `pure_` named colours.
| Base Color | Inherited by | Default |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- |
| **`pure_color_danger`** | **`pure_color_prompt_on_error`** | `red` |
| **`pure_color_dark`** | | `black` |
| **`pure_color_info`** | **`pure_color_git_unpulled_commits`**<br>**`pure_color_git_unpushed_commits`** | `cyan` |
| **`pure_color_light`** | **`pure_color_username_root`** | `white` |
| **`pure_color_mute`** | **`pure_color_git_branch`**<br>**`pure_color_git_dirty`**<br>**`pure_color_git_stash`**<br>**`pure_color_hostname`**<br>**`pure_color_at_sign`**<br>**`pure_color_username_normal`**<br>**`pure_color_virtualenv`** | `brblack` |
| **`pure_color_normal`** | **`pure_color_jobs`** | `normal` |
| **`pure_color_primary`** | **`pure_color_current_directory`** | `blue` |
| **`pure_color_success`** | **`pure_color_prompt_on_success`** | `magenta` |
| **`pure_color_warning`** | **`pure_color_command_duration`** | `yellow` |

## :+1: Contribute

**requirements:** [`docker`](https://docs.docker.com/install/) (isolate from your environment), get familiar with [CONTRIBUTING.md][contributing] guidelines.

Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by the container:

make build-pure-on FISH_VERSION=3.3.1
make dev-pure-on FISH_VERSION=3.3.1 CMD="fishtape tests/*.test.fish"

## :man_technologist: Maintainer

- [Édouard Lopez](https://github.com/edouard-lopez)

## :clap: Thanks

- [@andreiborisov](https://github.com/andreiborisov) for the [docker images][docker-images]
- [@jorgebucaran](https://github.com/jorgebucaran/) for [fishtape](https://github.com/jorgebucaran/fishtape)
If you have any ideas or suggestions, we encourage you to submit a pull request. Our team will review and discuss your contribution.

Checkout our [Contribution Guide][contribution] to get familiar with our conventions and requirements.

## :man_technologist: People

- [Édouard Lopez](https://github.com/edouard-lopez) product lead ;
- [@andreiborisov](https://github.com/andreiborisov) for the [docker images][docker-images] ;
- [@jorgebucaran](https://github.com/jorgebucaran/) for [fishtape](https://github.com/jorgebucaran/fishtape) ;
- [@rafaelrinaldi](https://github.com/rafaelrinaldi) for starting the project and publishing the initial releases

## :classical_building: License
## [MIT][MIT] License

[MIT][MIT]
[doc]: https://pure-fish.github.io/pure/
[configure]: https://pure-fish.github.io/pure/#configuration
[features]: https://pure-fish.github.io/pure/#overview
[contribution]:https://pure-fish.github.io/pure/contributing/

[to-set]: #paintbrush-configuration
[ci-link]: <https://github.com/pure-fish/pure/actions> "Github CI"
[ci-status]: https://img.shields.io/github/actions/workflow/status/pure-fish/pure/.github/workflows/ci.yml?style=flat-square

[fish-3]: <https://img.shields.io/badge/fish-v3-007EC7.svg?style=flat-square> "Support Fish 3"
[exit-code]: <https://github.com/sindresorhus/pure/wiki#show-exit-code-of-last-command-as-a-separate-prompt-character> "See pure-zsh wiki"
[fish-releases]: https://github.com/fish-shell/fish-shell/releases
[docker-images]: https://github.com/andreiborisov/docker-fish/
[MIT]: LICENSE.md
[fish-set-color]: https://fishshell.com/docs/current/cmds/set_color.html
[container-detection]: https://stackoverflow.com/q/23513045/802365

[release-version]: https://img.shields.io/github/v/tag/pure-fish/pure?label=latest%20&style=flat-square
[release-link]: https://github.com/pure-fish/pure/releases "GitHub tag (latest SemVer)"
[sponsors]: https://img.shields.io/github/sponsors/edouard-lopez?label=💰&style=flat-square "GitHub Sponsors"
[sponsor-link]: https://github.com/sponsors/edouard-lopez/ "Become a sponsor"

[contributing]: CONTRIBUTING.md
18 changes: 10 additions & 8 deletions docs/components/features-list.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,17 +67,19 @@

### Title

| Option | Default | Description |
| :------------------------------------------------------- | :------ | :---------------------------------------------------------------------------------------- |
| **`pure_symbol_title_bar_separator`** | `-` | Separator in terminal's windows title. |
| **`pure_shorten_window_title_current_directory_length`** | `0` | Shorten every window title path component but the last to X characters (0 do not shorten) |
| Option | Default | Description |
| :------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------- |
| **`pure_symbol_title_bar_separator`** | `-` | Separator in terminal's windows title. |
| **`pure_shorten_window_title_current_directory_length`** | `0` | Shorten every window title path component but the last to X characters (0 do not shorten) |
| **`pure_truncate_window_title_current_directory_keeps`** | `0` | Truncate working directory path in window title, but keeps the last to `n` components (`0` full path in window title) |

### Current Working Directory

| Option | Default | Description |
| :------------------------------------------------- | :------ | :---------------------------------------------------------------------------------- |
| **`pure_begin_prompt_with_current_directory`** | `true` | `true`: _`pwd` `git`, `SSH`, duration_.<br/>`false`: _`SSH` `pwd` `git`, duration_. |
| **`pure_shorten_prompt_current_directory_length`** | `0` | Shorten every prompt path component but the last to X characters (0 do not shorten) |
| Option | Default | Description |
| :------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------- |
| **`pure_begin_prompt_with_current_directory`** | `true` | `true`: _`pwd` `git`, `SSH`, duration_.<br/>`false`: _`SSH` `pwd` `git`, duration_. |
| **`pure_shorten_prompt_current_directory_length`** | `0` | Shorten every prompt path component but the last to X characters (0 do not shorten) |
| **`pure_truncate_prompt_current_directory_keeps`** | `0` | Truncate working directory path in prompt, but keeps the last to `n` components (`0` full path in current directory) |

### Check For New Release

Expand Down

0 comments on commit ad66c8a

Please sign in to comment.