mirror of https://github.com/oh-my-fish/oh-my-fish synced 2024-11-09 13:10:40 +00:00

Go to file

Bruno Pinto 890104ab2e Extract git clone calls into `omf.repo.clone`		2015-09-07 00:11:20 +01:00
bin	Back to oh-my-fish organization	2015-09-03 19:35:19 +01:00
db	Add python plugin	2015-09-04 23:11:12 -03:00
lib	Remove unnecessary code	2015-09-05 19:20:19 +01:00
pkg/omf	Extract git clone calls into `omf.repo.clone`	2015-09-07 00:11:20 +01:00
templates	Extracting template to a file and improving it	2015-08-28 12:53:37 +01:00
.editorconfig	%%% United States of the Fish → Wahoo + OMF %%%	2015-08-27 00:20:13 +09:00
.gitignore	fix omf new theme and remove default theme	2015-08-27 06:04:24 +09:00
.travis.yml	Only send travis notifications when build fails	2015-09-06 00:52:37 +01:00
CONTRIBUTING.md	Back to oh-my-fish organization	2015-09-03 19:35:19 +01:00
FAQ.md	Update install URL	2015-09-03 23:19:28 +01:00
init.fish	Remove global OSTYPE variable.	2015-09-05 19:20:24 +01:00
LICENSE	Undo Licence.. because you know what happened here	2015-09-03 23:20:42 +01:00
README.md	Back to oh-my-fish organization	2015-09-03 19:35:19 +01:00

README.md

The Fishshell Framework

About

Oh My Fish is an all-purpose framework for the 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.

Install

curl -L github.com/oh-my-fish/oh-my-fish/raw/master/bin/install | sh
omf help

Or download and run it yourself:

curl -L github.com/oh-my-fish/oh-my-fish/raw/master/bin/install > install
chmod +x install
./install

🔰 Getting Started

Oh My Fish includes a small utility omf to fetch and install new packages and themes.

`omf update`

Update framework and installed packages.

`omf install` `[package|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.

`omf list`

List installed packages.

`omf theme` `<theme>`

Apply a theme. To list available themes type omf theme.

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

`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>]`

Add a new package. To add a theme use omf submit themes/<name> <url>.

Make sure to send us a PR to update the registry.

`omf query` `<variable name>`

Use to inspect all session variables. Useful to dump path variables like $fish_function_path, $fish_complete_path, $PATH, etc.

`omf destroy`

Uninstall Oh My Fish. See uninstall for more information.

🚩 Advanced

Startup
Dotfiles
Core Library
Packages

Startup

This script runs each time a new session begins, autoloading packages, themes and your config path in that order.

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.

Dotfiles

The $OMF_CONFIG directory represents the user state of Oh My Fish, and is the perfect candidate for being added to your dotfiles and/or checked out to version control. There are two important files:

theme - The current theme
bundle - List of currently installed packages/themes

About the bundle

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.

Packages

Creating

A package name may only contain lowercase letters and hyphens to separate words.

To scaffold out a new package:

$ 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 for your utilities if applicable and describe how your package works in the README.md.

my_package.fish defines a single function:

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.

Submitting

Oh My Fish keeps a registry of packages under $OMF_PATH/db/.

To create a new entry run:

omf submit pkg/my_package .../my_package.git

Similarly for themes use:

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 to update the global registry.

Initialization

If you want to be notified when your package loads, declare the following function in your my_package.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.

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:

set -g OMF_IGNORE skip this that ...