- Clean up README formatting.
- Move all configuration documentation from functions into the README.
- Add missing documentation for a bunch of other options.
Fixes#337
@ -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.
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.
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.
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` toalways show full paths in the title.
@ -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`:
Justin Hileman
2 months ago