From 2b060736b342f3b60dccabe913253acb203c58d1 Mon Sep 17 00:00:00 2001 From: Justin Hileman Date: Tue, 5 Mar 2024 17:57:16 -0500 Subject: [PATCH] Update configuration option documentation. - Clean up README formatting. - Move all configuration documentation from functions into the README. - Add missing documentation for a bunch of other options. Fixes #337 --- README.md | 302 ++++++++++++++++++++++--------- functions/fish_prompt.fish | 38 +--- functions/fish_right_prompt.fish | 4 +- functions/fish_title.fish | 6 +- 4 files changed, 221 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index a06a258..6897765 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,8 @@ ![bobthefish][btf-screencast] -### Installation + +## Installation Be sure to have Oh My Fish installed. Then just: @@ -24,7 +25,8 @@ You will need a [Powerline-patched font][btf-patching] for this to work, unless This theme is based loosely on [agnoster][btf-agnoster]. -### Features + +## Features * A helpful, but not too distracting, greeting. * A subtle timestamp hanging out off to the right. @@ -35,7 +37,8 @@ This theme is based loosely on [agnoster][btf-agnoster]. * Visual indication that you can't write to the current directory. -### The Prompt + +## The Prompt * Status flags: * Previous command failed (**`!`**) @@ -63,89 +66,222 @@ This theme is based loosely on [agnoster][btf-agnoster]. * Abbreviated project-relative path -### Configuration + +## Configuration You can override some of the following default options in your fish config (e.g. `~/.config/fish/config.fish`, `~/.config/omf/init.fish`, or a script in `~/.config/fish/conf.d/`): ```fish -set -g theme_display_git no -set -g theme_display_git_dirty no -set -g theme_display_git_untracked no -set -g theme_display_git_ahead_verbose yes -set -g theme_display_git_dirty_verbose yes -set -g theme_display_git_stashed_verbose yes -set -g theme_display_git_default_branch yes -set -g theme_git_default_branches master main -set -g theme_git_worktree_support yes -set -g theme_use_abbreviated_branch_name yes -set -g theme_display_vagrant yes -set -g theme_display_docker_machine no -set -g theme_display_k8s_context yes -set -g theme_display_hg yes -set -g theme_display_virtualenv no -set -g theme_display_virtualenv verbose -set -g theme_display_nix no -set -g theme_display_ruby no -set -g theme_display_node yes -set -g theme_display_user ssh -set -g theme_display_hostname ssh -set -g theme_display_vi no -set -g theme_display_date no -set -g theme_display_cmd_duration yes -set -g theme_title_display_process yes -set -g theme_title_display_path no -set -g theme_title_display_user yes -set -g theme_title_use_abbreviated_path no -set -g theme_date_format "+%a %H:%M" -set -g theme_date_timezone America/Los_Angeles -set -g theme_avoid_ambiguous_glyphs yes -set -g theme_powerline_fonts no -set -g theme_nerd_fonts yes -set -g theme_show_exit_status yes -set -g theme_display_jobs_verbose yes -set -g default_user your_normal_user -set -g theme_color_scheme dark -set -g fish_prompt_pwd_dir_length 0 -set -g theme_project_dir_length 1 -set -g theme_show_project_parent yes -set -g theme_newline_cursor yes -set -g theme_newline_prompt '$ ' ``` -**Git options** - -- `theme_display_git_default_branch`. By default theme will hide/collapse the branch name in your prompt when you are using a Git _default branch_ i.e. historically `master` and often `main` now. Set to `yes` to stop these branches from being hidden/collapsed. -- `theme_git_default_branches`. The big cloud repos (GitHub, Bitbucket, GitLab et al.) are moving away from using `master` as the default branch name, and allow you to choose your own. As of version **2.28**, Git also supports custom default branch names via the `init.defaultBranch` config option. If our defaults of `master main` don't suit you, you can add/remove names in thist list i.e. `main trunk`. This ensures correct hiding/collapsing behaviour with custom default branch names (unless option above is activated). - -**Title options** - -- `theme_title_display_process`. By default theme doesn't show current process name in terminal title. If you want to show it, just set to `yes`. -- `theme_title_display_path`. Use `no` to hide current working directory from title. -- `theme_title_display_user`. Set to `yes` to show the current user in the tab title (unless you're the default user). -- `theme_title_use_abbreviated_path`. Default is `yes`. This means your home directory will be displayed as `~` and `/usr/local` as `/u/local`. Set it to `no` if you prefer full paths in title. - -**Prompt options** - -- `theme_display_ruby`. Use `no` to completely hide all information about Ruby version. By default Ruby version displayed if there is the difference from default settings. -- `theme_display_node`. If set to `always`, will display current NPM, NVM or FNM node version. If set to `yes`, will display the version if an `.nvmrc`, `.node-version` or `package.json` file is found in the parent directories. -- `theme_display_vagrant`. This feature is disabled by default, use `yes` to display Vagrant status in your prompt. Please note that only the VirtualBox and VMWare providers are supported. -- `theme_display_vi`. By default the vi mode indicator will be shown if vi or hybrid key bindings are enabled. Use `no` to hide the indicator, or `yes` to show the indicator. -- `theme_display_k8s_context`. This feature is disabled by default. Use `yes` to show the current kubernetes context (`> kubectl config current-context`). -- `theme_display_k8s_namespace`. This feature is disabled by default. Use `yes` to show the current kubernetes namespace. -- `theme_display_aws_vault_profile`. This feature is disabled by default. Use `yes` to show the currently executing [AWS Vault](https://github.com/99designs/aws-vault) profile. -- `theme_display_user`. If set to `yes`, display username always, if set to `ssh`, only when an SSH-Session is detected, if set to no, never. -- `theme_display_hostname`. Same behaviour as `theme_display_user`. -- `theme_display_sudo_user`. If set to `yes`, displays the sudo-username in a root shell. For example, when calling `sudo -s` and having this option set to `yes`, the username of the user, who called `sudo -s`, will be displayed. -- `theme_show_exit_status`. Set this option to `yes` to have the prompt show the last exit code if it was non_zero instead of just the exclamation mark. -- `theme_display_jobs_verbose`. If set to `yes` this option displays the number of currently running background jobs next to the percent sign. -- `theme_git_worktree_support`. If you do any git worktree shenanigans, setting this to `yes` will fix incorrect project-relative path display. If you don't do any git worktree shenanigans, leave it disabled. It's faster this way :) -- `theme_use_abbreviated_branch_name`. Set to `yes` to truncate git branch names in the prompt. -- `fish_prompt_pwd_dir_length`. bobthefish respects the Fish `$fish_prompt_pwd_dir_length` setting to abbreviate the prompt path. Set to `0` to show the full path, `1` (default) to show only the first character of each parent directory name, or any other number to show up to that many characters. -- `theme_project_dir_length`. The same as `$fish_prompt_pwd_dir_length`, but for the path relative to the current project root. Defaults to `0`; set to any other number to show an abbreviated path. -- `theme_show_project_parent`. Set to `no` to only show the project directory name, and not its parent path, when inside a project. -- `theme_newline_cursor`. Use `yes` to have cursor start on a new line. By default the prompt is only one line. When working with long directories it may be preferrend to have cursor on the next line. Setting this to `clean` instead of `yes` suppresses the caret on the new line. -- `theme_newline_prompt`. Use a custom prompt with newline cursor. By default this is the chevron right glyph or `>` when powerline fonts are disabled. - -**Color scheme options** + + +### Prompt options + +#### `set -g theme_display_vi yes` + +By default the vi mode indicator will be shown if vi or hybrid key bindings are enabled. Use `no` to always hide the indicator, or `yes` to always show the indicator. + +#### `set -g theme_show_exit_status yes` + +Use `yes` to show any non-zero exit code next to the exclamation mark. + +#### `set -g theme_display_jobs_verbose yes` + +Use `yes` to display the number of currently running background jobs next to the percent sign. + +#### `set -g theme_display_user yes` + +Set to `yes` to always display the username, to `ssh` to display only when an SSH session is active, or to `no` to never display the username. + +#### `set -g default_user your_normal_user` + +If a `default_user` is provided, the username will only be shown when it differs from the default. + +#### `set -g theme_display_sudo_user yes` + +If set to `yes`, displays the sudoer's username in a root shell. For example, when calling `sudo -s` with this option set to `yes`, the user who called `sudo -s` will be displayed. + +#### `set -g theme_display_hostname yes` + +Set to `yes` to always display the hostname, to `ssh` to display only when an SSH session is active, or to `no` to never display the hostname. + +#### `set -g fish_prompt_pwd_dir_length 1` + +Bobthefish respects the Fish `$fish_prompt_pwd_dir_length` setting to abbreviate the prompt path; set to `0` to show the full path, `1` (default) to show only the first character of each parent directory name, or any other number to show up to that many characters. + +#### `set -g theme_project_dir_length 1` + +The same as `$fish_prompt_pwd_dir_length`, but for the path relative to the current project root. Defaults to `0`; set to any other number to show an abbreviated path. + +#### `set -g theme_show_project_parent no` + +Use `no` to only show the project directory name, and not its parent path, when inside a project. + +#### `set -g theme_newline_cursor yes` + +Use `yes` to place the cursor on the next line, rather than the same line as the prompt. Setting this to `clean` instead of `yes` suppresses the caret on the new line. + +#### `set -g theme_newline_prompt "\$"` + +Use a custom prompt with newline cursor. By default this is the chevron right glyph or `>` when powerline fonts are disabled. + +#### `set -g theme_avoid_ambiguous_glyphs yes` + +You probably don't need this option, unless your terminal doesn't like Unicode. Setting to `yes` will avoid ambiguous-width characters in an attempt to + +#### `set -g theme_powerline_fonts no` + +Bobthefish really likes Powerline-enhanced fonts. If you can't make that work, set to `no` to use plaintext fallbacks. + +#### `set -g theme_nerd_fonts yes` + +Bobthefish likes Nerd Fonts even better! Use `yes` if you've got Nerd Font capable fonts. + +#### `set -g theme_color_scheme dark` + +See below for all the color scheming you can handle. + + + +### Virtual environments and version manager options + +#### `set -g theme_display_vagrant yes` + +This feature is disabled by default, use `yes` to display Vagrant status in your prompt. Please note that only the VirtualBox and VMWare providers are supported. + +#### `set -g theme_display_docker_machine no` + +Use `no` to disable the current Docker machine name. + +#### `set -g theme_display_ruby no` + +Use `no` to disable Ruby version information. By default, the Ruby version is displayed unless it's your system Ruby version. + +#### `set -g theme_display_virtualenv no` + +Use `no` to disable Python version information. By default, the Python version is shown when it's interesting, along with the Virtualenv or Conda environmenmt. + +#### `set -g theme_display_go verbose` + +Use `no` to disable the Go version information. Set to `verbose` to show both the required and current Go version. + +#### `set -g theme_display_node yes` + +This feature is disabled by default. Use `yes`, display the version if an `.nvmrc`, `.node-version` or `package.json` file is found in the parent path. Set to `always` to always display the current NPM, NVM or FNM node version. + +#### `set -g theme_display_nix no` + +Use `no` to disable Nix environment information. + +#### `set -g theme_display_k8s_context yes` + +This feature is disabled by default. Use `yes` to show the current Kubernetes context (`> kubectl config current-context`). + +#### `set -g theme_display_k8s_namespace yes` + +This feature is disabled by default. Use `yes` to show the current Kubernetes namespace. + +#### `set -g theme_display_aws_vault_profile yes` + +This feature is disabled by default. Use `yes` to show the currently executing [AWS Vault](https://github.com/99designs/aws-vault) profile. + + + +### Git (and other VCS) options + +#### `set -g theme_display_git no` + +Use `no` to disable Git integration. If you're doing this for performance reasons, try some of the options below before disabling it entirely! + +#### `set -g theme_display_git_dirty no` + +Use `no` to hide Git dirty state. Set the Git `bash.showDirtyState` option on a per-repository basis to disable it just for especially large repos. + +#### `set -g theme_display_git_dirty_verbose yes` + +This feature is disabled by default. Use `yes` to show more verbose dirty state information. + +#### `set -g theme_display_git_untracked no` + +Use `no` to hide Git untracked file state. Set the Git `bash.showUntrackedFiles` option on a per-repository basis to disable it just for especially large repos. + +#### `set -g theme_display_git_ahead_verbose yes` + +This feature is disabled by default. Use `yes` to show more verbose ahead/behind state information. + +#### `set -g theme_display_git_stashed_verbose yes` + +This feature is disabled by default. Use `yes` to show more verbose stashed state information. + +#### `set -g theme_display_git_default_branch yes` + +By default, Bobthefish hides the default branch name (e.g. `main` or `master`). Use `yes` to always show these branche names. + +#### `set -g theme_git_default_branches main trunk` + +By default, Bobthefish hides default branch names (e.g. `main` or `master`). To hide other branch names, you can set a custom default branch name via the `init.defaultBranch` Git config option, or override the list entirely. + +#### `set -g theme_use_abbreviated_branch_name yes` + +This feature is disabled by default. Use `yes` to truncate extremely long Git branch names. + +#### `set -g theme_git_worktree_support yes` + +If you do any Git worktree shenanigans, setting this to `yes` will fix incorrect project-relative paths. If you don't do any Git worktree shenanigans, leave it disabled. It's faster this way :) + +#### `set -g theme_display_hg yes` + +This feature is disabled by default. Use `yes` to enable Mercurial support in Bobthefish. If you don't use Mercurial, leave it disabled because it's ... not fast. + +#### `set -g theme_vcs_ignore_paths /some/path /some/other/path{foo,bar}` + +Ignore project paths for Git or Mercurial. Supports glob patterns. + + + +### Right prompt options + +The right prompt can be configured with the following options, or overridden entirely by supplying your own `fish_right_prompt` function. + +#### `set -g theme_display_date` + +Use `no` to disable the date in the right prompt. + +#### `set -g theme_date_format +%c` + +Customize date formatting. See `man date` for more information. + +#### `set -g theme_date_timezone America/Los_Angeles` + +Supply a TZ argument variable for date formatting. See `man date` for more information. + +#### `set -g theme_display_cmd_duration no` + +Use `no` to disable command duration in the right prompt. + + + +### Title options + +#### `set -g theme_title_display_process yes` + +This feature is disabled by default. Use `yes` to show current process name in the terminal title. + +#### `set -g theme_title_display_path no` + +Use `no` to hide current working directory from the terminal title. + +#### `set -g theme_title_display_user yes` + +Use `yes` to show the current user in the tab title (unless you're the default user). + +#### `set -g theme_title_use_abbreviated_path no` + +By default, directory names will be abbreviated in the terminal title, for example `~` instead of `$HOME` and `/u/local` instead of `/usr/local`. Set to `no` to always show full paths in the title. + + + +### Color schemes | ![dark][btf-dark] | ![light][btf-light] | | --------------------------- | --------------------------------------- | @@ -204,10 +340,8 @@ variables to set the colors of the prompt. See the "Colors" section of `fish_prompt.fish` for details. -**VCS options** -- `set -g theme_vcs_ignore_paths /some/path /some/other/path{foo,bar}`. Ignore project paths for Git or Mercurial. Supports glob patterns. -### Overrides +## Overrides You can disable the theme default greeting, vi mode prompt, right prompt, or title entirely — or override with your own — by adding custom functions to `~/.config/fish/functions`: diff --git a/functions/fish_prompt.fish b/functions/fish_prompt.fish index 9b987b1..91a2c59 100644 --- a/functions/fish_prompt.fish +++ b/functions/fish_prompt.fish @@ -15,44 +15,8 @@ # # https://github.com/ryanoasis/nerd-fonts # -# You can override some default prompt options in your config.fish: +# See README.md for setup and configuration options. # -# set -g theme_display_git no -# set -g theme_display_git_dirty no -# set -g theme_display_git_untracked no -# set -g theme_display_git_ahead_verbose yes -# set -g theme_display_git_dirty_verbose yes -# set -g theme_display_git_stashed_verbose yes -# set -g theme_display_git_default_branch yes -# set -g theme_git_default_branches main trunk -# set -g theme_git_worktree_support yes -# set -g theme_display_vagrant yes -# set -g theme_display_docker_machine no -# set -g theme_display_k8s_context yes -# set -g theme_display_k8s_namespace no -# set -g theme_display_aws_vault_profile yes -# set -g theme_display_hg yes -# set -g theme_display_virtualenv no -# set -g theme_display_virtualenv verbose -# set -g theme_display_nix no -# set -g theme_display_ruby no -# set -g theme_display_go no -# set -g theme_display_user ssh -# set -g theme_display_hostname ssh -# set -g theme_display_sudo_user yes -# set -g theme_display_vi no -# set -g theme_display_node yes -# set -g theme_avoid_ambiguous_glyphs yes -# set -g theme_powerline_fonts no -# set -g theme_nerd_fonts yes -# set -g theme_show_exit_status yes -# set -g theme_display_jobs_verbose yes -# set -g default_user your_normal_user -# set -g theme_color_scheme dark -# set -g fish_prompt_pwd_dir_length 0 -# set -g theme_project_dir_length 1 -# set -g theme_show_project_parent no -# set -g theme_newline_cursor yes # ============================== # Helper methods diff --git a/functions/fish_right_prompt.fish b/functions/fish_right_prompt.fish index ef54772..45e14d6 100644 --- a/functions/fish_right_prompt.fish +++ b/functions/fish_right_prompt.fish @@ -1,6 +1,4 @@ -# You can override some default right prompt options in your config.fish: -# set -g theme_date_format "+%a %H:%M" -# set -g theme_date_timezone America/Los_Angeles +# See "Right prompt options" in README.md for configuration options function __bobthefish_cmd_duration -S -d 'Show command duration' [ "$theme_display_cmd_duration" = "no" ] diff --git a/functions/fish_title.fish b/functions/fish_title.fish index c9f40ce..91793c2 100644 --- a/functions/fish_title.fish +++ b/functions/fish_title.fish @@ -1,8 +1,4 @@ -# You can override some default title options in your config.fish: -# set -g theme_title_display_process no -# set -g theme_title_display_path no -# set -g theme_title_display_user yes -# set -g theme_title_use_abbreviated_path no +# See "Title options" in README.md for configuration options function __bobthefish_title_user -S -d 'Display actual user if different from $default_user' if [ "$theme_title_display_user" = 'yes' ]