The Fish Shell Framework
The Fishshell Framework
Oh My Fish provides core infrastructure to allow you to install packages which extend or modify the look of your shell. It's fast, extensible and easy to use.
You can get started right away with the default setup by running this in your terminal:
curl -L https://get.oh-my.fish | fish
This will download the installer script and start the installation. Alternatively, you can download the installer and customize your install:
curl -L https://get.oh-my.fish > install fish install --path=~/.local/share/omf --config=~/.config/omf
You can verify the integrity of the downloaded installer by verifying the script against this checksum:
bb1f4025934600ea6feef2ec11660e17e2b6449c5a23c033860aed712ad328c9 install
You can also install Oh My Fish with Git or with an offline source tarball downloaded from the releases page:
# with git $ git clone https://github.com/oh-my-fish/oh-my-fish $ cd oh-my-fish $ bin/install --offline # with a tarball $ curl -L https://get.oh-my.fish > install $ fish install --offline=omf.tar.gz
Run
install --helpfor a complete list of install options you can customize.
defaulttheme features a right prompt, so it's necessary to use an alternative theme until a fix is released. (see #541)
Oh My Fish includes a small utility
omfto fetch and install new packages and themes.
omf update
[omf]
[...]
Update Oh My Fish, all package repositories, and all installed packages.
omf update omf.
omf install
[|]
Install one or more packages.
omf install URL
omf repositories
[list|add|remove]
Manage user-installed package repositories. Package repositories are where packages come from used by commands like
omf install. By default the official repository is always installed and available.
omf list
List installed packages.
omf theme
Apply a theme. To list available themes, type
omf theme. You can also preview available themes before installing.
omf remove
Remove a theme or package.
Packages can use uninstall hooks, so custom cleanup of resources can be done when uninstalling it. See Uninstall for more information.
omf reload
Reload Oh My Fish and all plugins by using
execto replace current shell process with a brand new.
This command tries to be as safe as possible, mitigating side-effects caused by
execand preventing the reload in case of background processes.
omf new plugin | theme
Scaffold out a new plugin or theme.
This creates a new directory under
$OMF_CONFIG/{pkg | themes}/with a template.
omf search
-t|--theme / -p|--package
Searches Oh My Fish's database for a given package, theme or both. It also supports fuzzy search, so if you are not sure of the name you can simply
omf search simple.
omf channel
Gets or changes the update channel.
Two channels are available by default: the
stablechannel provides stable updates with the latest tagged version of Oh My Fish, and
devwhich provides the latest changes under development. The update channel currently set determines what version
omf updatewill upgrade to.
omf doctor
Use to troubleshoot before opening an issue.
omf destroy
Uninstall Oh My Fish.
Oh My Fish installer adds a snippet to fish's user config files (
~/.config/fish/conf.d/) which calls OMF's startup code.
Notice that the scripts in that directory are sourced in the order that the filesystem sees them, and so it may be necessary to prefix your script files with ordering numbers.
For example:
a_script.fishwill take precedence over the
omf.fishsnippet. So if
a_script.fishdepends on plugins managed by OMF, consider renaming the script file to
xx_a_script.fish.
Similarly, to make sure that a script runs before
omf.fish, you may prefix it with
00_. Alternatively,
~/.config/omf/before.init.fishmay be used.
Every time you open a new shell, the startup code initializes Oh My Fish installation path and the config path (
~/.config/omfby default), sourcing the
init.fishscript afterwards, which autoloads packages, themes and your custom init files.
For more information check the FAQ.
The
$OMF_CONFIGdirectory represents the user state of Oh My Fish. It is the perfect candidate for being added to your dotfiles and/or checked out to version control. There you can find three important files:
theme- The current theme
bundle- List of currently installed packages/themes
channel- The channel from which OMF gets updates (stable / dev)
And you may create and customize these special files:
init.fish- Custom script sourced after shell start
before.init.fish- Custom script sourced before shell start
key_bindings.fish- Custom key bindings where you can use the
bindcommand freely
init.fish
One of the most common startup commands used in
init.fishis variables definition. Quite likely, such variables need to be available in any shell session. To achieve this, define them globally. For example:
# Golang developers might need this one set -xg GOPATH $HOME/gocodePython developers otherwise
set -xg PYTHONDONTWRITEBYTECODE 1
Every time a package/theme is installed or removed, the
bundlefile is updated. You can also edit it manually and run
omf installafterwards to satisfy the changes. Please note that while packages/themes added to the bundle get automatically installed, a package/theme removed from bundle isn't removed from user installation.
In fish 2.2, there is no
conf.ddirectory, so the startup code has to be placed in the fish config file (
~/.config/fish/config.fish).
It's highly recommended that your custom startup commands go into
init.fishfile instead of
~/.config/fish/config.fish, as this allows you to keep the whole
$OMF_CONFIGdirectory under version control.
If you need startup commands to be run before Oh My Fish begins loading plugins, place them in
before.init.fishinstead. If you're unsure, it is usually best to put things in
init.fish.
Oh My Fish uses an advanced and well defined plugin architecture to ease plugin development, including init/uninstall hooks, function and completion autoloading. See the packages documentation for more details.