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.
Oh My Fish is an all-purpose framework for the [fishshell][Fishshell]. It looks after your configuration, themes and packages. It's lightning fast and easy to use.
We love contributions, [fork and send us a PR](https://github.com/oh-my-fish/oh-my-fish/fork).
<br><br>
# Install
@ -61,71 +24,62 @@ chmod +x install
./install
```
# :beginner: Getting Started
# Getting Started
Oh My Fish includes a small utility `omf` to fetch and install new packages and themes.
## `omf update`
#### `omf update`
Update framework and installed packages.
Update the framework and installed packages.
##`omf install` _`[package|url ...]`_
#### `omf install` _`[<name>|<url>]`_
Install one _or more_ packages.
- You can install packages directly by URL via `omf install URL`
- When called without arguments, install missing packages from [bundles](#dotfiles).
- When called without arguments, install missing packages from [bundle](#dotfiles).
## `omf list`
#### `omf list`
List installed packages.
## `omf theme` _`<theme>`_
#### `omf theme` _`<theme>`_
Apply a theme. To list available themes type `omf theme`.
## `omf remove` _`<name>`_
#### `omf remove` _`<name>`_
Remove a theme or package.
> Packages subscribed to `uninstall_<pkg>` events are notified before the package is removed to allow custom cleanup of resources. See [Uninstall](#uninstall).
> Packages subscribed to `uninstall_<pkg>` events are notified before the package is removed, so custom cleanup of resources can be done. See [Uninstall](/docs/Packages.md#uninstall) for more information.
## `omf new pkg | theme` _`<name>`_
#### `omf new pkg | theme` _`<name>`_
Scaffold out a new package or theme.
> This creates a new directory under `$OMF_CONFIG/{pkg | themes}/` with a template.
## `omf submit`_`pkg/<name>`_ _`[<url>]`_
#### `omf submit`_`pkg/<name>`_ _`[<url>]`_
Add a new package. To add a theme use `omf submit`_`themes/<name>`__`<url>`_.
Make sure to [send us a PR][omf-pulls-link] to update the registry.
## `omf query` _`<variablename>`_
#### `omf query` _`<variablename>`_
Use to inspect all session variables. Useful to dump _path_ variables like `$fish_function_path`, `$fish_complete_path`, `$PATH`, etc.
## `omf destroy`
#### `omf destroy`
Uninstall Oh My Fish. See [uninstall](#uninstall) for more information.
Uninstall Oh My Fish.
# :triangular_flag_on_post: Advanced
+ [Startup](#startup)
+ [Dotfiles](#dotfiles)
+ [Core Library](#core-library)
+ [Packages](#packages)
+ [Creating](#creating)
+ [Submitting](#submitting)
+ [Initialization](#initialization)
+ [Uninstall](#uninstall)
+ [Ignoring](#ignoring)
# Advanced
## Startup
Oh My Fish installer places its startup code in your fish config file (`~/.config/fish/config.fish`).
This script runs each time a new session begins, autoloading packages, themes and your _config_ path in that order.
## Startup
The _config_ path (`~/.config/omf` by default) is defined by `$OMF_CONFIG` in `~/.config/fish/config.fish`. Modify this to load your own configuration, if you have any, as discussed in the [FAQ](FAQ.md#what-does-oh-my-fish-do-exactly).
Everytime you open a new shell the startup code initializes Oh My Fish installation path and the _config_ path (`~/.config/omf` by default), sourcing the [`init.fish`](init.fish) script afterwards, which autoload packages, themes and your custom init file. For more information check the [FAQ](docs/FAQ.md#what-does-oh-my-fish-do-exactly).
## Dotfiles
@ -139,109 +93,16 @@ candidate for being added to your dotfiles and/or checked out to version control
Everytime a package/theme is installed or removed the `bundle` file is updated. You can also edit it manually and run `omf install` afterwards to satisfy the changes. Please note that while packages/themes added to the bundle gets automagically installed, a package/theme removed from bundle isn't removed from user installation.
## Core Library
The core library is a minimum set of basic utility functions that extend your shell.
+ [See the documentation](/lib/README.md).
## Packages
### Creating
> A package name may only contain lowercase letters and hyphens to separate words.
To scaffold out a new package:
```fish
$ omf new pkg my_package
my_package/
README.md
my_package.fish
completions/my_package.fish
```
> Use `omf new theme my_theme` for themes.
Please provide [auto completion](http://fishshell.com/docs/current/commands.html#complete) for your utilities if applicable and describe how your package works in the `README.md`.
`my_package.fish` defines a single function:
```fish
function my_package -d "My package"
end
```
> Bear in mind that fish lacks a private scope so consider the following options to avoid polluting the global namespace:
+ Prefix functions: `my_package_my_func`.
+ Using [blocks](http://fishshell.com/docs/current/commands.html#block).
### Submitting
Oh My Fish keeps a registry of packages under `$OMF_PATH/db/`.
To create a new entry run:
```fish
omf submit pkg/my_package .../my_package.git
```
Similarly for themes use:
```fish
omf submit theme/my_theme .../my_theme.git
```
This will add a new entry to your local copy of the registry. Please [send us a PR][omf-pulls-link] to update the global registry.
### Initialization
If you want to be [notified](http://fishshell.com/docs/current/commands.html#emit) when your package loads, declare the following function in your `my_package.fish`:
```fish
function init -a path --on-event init_mypkg
end
```
Use this event to modify the environment, load resources, autoload functions, etc. If your package does not export any functions, you can still use this event to add functionality to your package.
### Uninstall
Oh My Fish emits `uninstall_<pkg>` events before a package is removed via `omf remove <pkg>`. Subscribers can use the event to clean up custom resources, etc.
```fish
function uninstall --on-event uninstall_pkg
end
```
### Ignoring
Remove any packages you wish to turn off using `omf remove <package name>`. Alternatively, you can set a global env variable `$OMF_IGNORE` in your `~/.config/fish/config.fish` with the packages you wish to ignore. For example:
```fish
set -g OMF_IGNORE skip this that ...
```
## Creating Packages
Oh My Fish uses an advanced and well defined plugin architecture to ease plugin development, including init/uninstall events and function autoloading. [See the documentation](docs/Packages.md) for more details.
To learn package creation let's create a new package that will provide a `hello_world` command for your shell. Package names may only contain lowercase letters and hyphens to separate words.
Oh My Fish can scaffold a package structure for you. Use the command `omf new`:
```fish
$ omf new pkg hello_world
```
> Use `omf new theme my_theme_name` for themes.
The utily changes the current directory to the newly created package:
```
$ ls -l
README.md
hello_world.fish
completions/hello_world.fish
```
Always describe how your package works in the `README.md`. Also read more about [auto completion](http://fishshell.com/docs/current/commands.html#complete) and also take care to provide it for your utilities when applicable.
`hello_world.fish` defines a single function:
```fish
function hello_world -d "Prints hello world"
echo "Hello World!"
end
```
Each function in your package must be declared in its own file. This is required by fish autoloading mechanism, which loads functions on demand, avoiding loading unused functions.
Bear in mind that fish lacks a private scope, so if you need to split your package into functions, consider prefixing private functions like this: `__hello_world.my_extra_function`, to avoid both name clashes and global namespace pollution.
# Events
Packages were designed to take advantages of fish events. There are currently two events that Oh My Fish will emit to your package:
## Initialization
If you want to be [notified](http://fishshell.com/docs/current/commands.html#emit) when your package loads, declare the following function in your `hello_world.fish`:
```fish
function init -a path --on-event init_hello_world
echo "hello_world initialized"
end
```
Use this event to modify the environment, load resources, autoload functions, etc. If your package does not export any functions, you can still use this event to add functionality to your package.
## Uninstall
Oh My Fish emits `uninstall_<pkg>` events before a package is removed via `omf remove <pkg>`. Subscribers can use the event to clean up custom resources, etc.
```fish
function uninstall --on-event uninstall_hello_world
end
```
# Make it public
Oh My Fish keeps a registry of public packages under `$OMF_PATH/db/`.
To add your package to the registry you need to:
```fish
# For packages:
omf submit pkg/hello_world .../hello_world.git
# For themes
omf submit theme/my_theme .../my_theme_name.git
```
This will add a new entry to your local copy of the registry. Now you just need to [send us a PR][omf-pulls-link] to update the global registry.
Derek Willian Stavis
9 years ago
