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.

Also in  🇷🇺 🇨🇳 🇺🇦 🇧🇷 🇪🇸

Table of contents

• Installation
• Getting Started (command descriptions)
• Advanced
  • Startup
  • Dotfiles
• Creating Packages

Installation

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 --help

Requirements

• fish shell, version 2.2 or later
• git, version 1.9.5 or later

Known Issues

• Due to a regression bug in fish 2.6 with some terminal emulators, right prompts make the shell unusable. OMF's

  default

  theme features a right prompt, so it's necessary to use an alternative theme until a fix is released. (see #541)

Getting Started

Oh My Fish includes a small utility

omf

omf update

[omf]

[...]

Update Oh My Fish, all package repositories, and all installed packages.

• When called without arguments, update core and all installed packages.
• You can choose to update only the core, by running

  omf update omf

  .
• For selective package update, list only the names of packages you wish to update. You may still include "omf" in the list to update the core as well.

omf install

[|]

Install one or more packages.

• You can install packages directly by URL via

  omf install URL

• When called without arguments, install missing packages from bundle.

omf repositories

[list|add|remove]

Manage user-installed package repositories. Package repositories are where packages come from used by commands like

omf install

omf list

List installed packages.

omf theme

Apply a theme. To list available themes, type

omf theme

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

exec

This command tries to be as safe as possible, mitigating side-effects caused by

exec

and 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

stable

dev

omf update

omf doctor

Use to troubleshoot before opening an issue.

omf destroy

Uninstall Oh My Fish.

Advanced

Oh My Fish installer adds a snippet to fish's user config files (

~/.config/fish/conf.d/

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.fish

omf.fish

a_script.fish

xx_a_script.fish

Similarly, to make sure that a script runs before

omf.fish

00_

~/.config/omf/before.init.fish

Startup

Every time you open a new shell, the startup code initializes Oh My Fish installation path and the config path (

~/.config/omf

init.fish

For more information check the FAQ.

Dotfiles

The

$OMF_CONFIG

• 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

  bind

  command freely

Setting variables in

init.fish

One of the most common startup commands used in

init.fish

# Golang developers might need this one
set -xg GOPATH $HOME/gocode

Python developers otherwise
set -xg PYTHONDONTWRITEBYTECODE 1

About the bundle

Every time a package/theme is installed or removed, the

bundle

omf install

Older fish versions

In fish 2.2, there is no

conf.d

~/.config/fish/config.fish

It's highly recommended that your custom startup commands go into

init.fish

~/.config/fish/config.fish

$OMF_CONFIG

If you need startup commands to be run before Oh My Fish begins loading plugins, place them in

before.init.fish

init.fish

Creating Packages

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.