ef62b6595d
Adds a badge showing the number of people helping this repo on CodeTriage. [![Open Source Helpers](https://www.codetriage.com/oh-my-fish/oh-my-fish/badges/users.svg)](https://www.codetriage.com/oh-my-fish/oh-my-fish) ## What is CodeTriage? CodeTriage is an Open Source app that is designed to make contributing to Open Source projects easier. It works by sending subscribers a few open issues in their inbox. If subscribers get busy, there is an algorithm that backs off issue load so they do not get overwhelmed [Read more about the CodeTriage project](https://www.codetriage.com/what). ## Why am I getting this PR? Your project was picked by the human, @schneems. They selected it from the projects submitted to https://www.codetriage.com and hand edited the PR. How did your project get added to [CodeTriage](https://www.codetriage.com/what)? Roughly over 3 years ago, [Yuri-M-Dias](https://github.com/Yuri-M-Dias) added this project to CodeTriage in order to start contributing. ## What does adding a badge accomplish? Adding a badge invites people to help contribute to your project. It also lets developers know that others are invested in the longterm success and maintainability of the project. You can see an example of a CodeTriage badge on these popular OSS READMEs: - [![Email clients like GMAIL do not render SVG images](https://www.codetriage.com/rails/rails/badges/users.svg)](https://www.codetriage.com/rails/rails) https://github.com/rails/rails - [![Email clients like GMAIL do not render SVG images](https://www.codetriage.com/crystal-lang/crystal/badges/users.svg)](https://www.codetriage.com/crystal-lang/crystal) https://github.com/crystal-lang/crystal ## Have a question or comment? While I am a bot, this PR was manually reviewed and monitored by a human - @schneems. My job is writing commit messages and handling PR logistics. If you have any questions, you can reply back to this PR and they will be answered by @schneems. If you do not want a badge right now, no worries, close the PR, you will not hear from me again. Thanks for making your project Open Source! Any feedback is greatly appreciated. |
||
---|---|---|
.github/ISSUE_TEMPLATE | ||
bin | ||
docs | ||
lib | ||
pkg | ||
templates | ||
tests | ||
tools | ||
.gitattributes | ||
.gitignore | ||
.travis.yml | ||
AUTHORS | ||
CHANGELOG.md | ||
CODEOWNERS | ||
CONTRIBUTING.md | ||
Dockerfile | ||
init.fish | ||
LICENSE | ||
README.md | ||
repositories |
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.
Table of contents
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:
434264c56e3a7bb74733d9b293d72403c404e0a0bded3e632433d391d302504e 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
for a complete list of install options you can customize.
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'sdefault
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
to fetch and install new packages and themes.
omf update
[omf]
[<package>...]
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
[<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 bundle.
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
<theme>
Apply a theme. To list available themes, type omf theme
. You can also preview available themes before installing.
omf remove
<name>
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
to replace current shell process with a brand new.
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
<name>
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
<name>
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
channel provides stable updates with the latest tagged version of Oh My Fish, and dev
which provides the latest changes under development. The update channel currently set determines what version omf update
will upgrade to.
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/
) 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.fish
will take precedence over the omf.fish
snippet.
So if a_script.fish
depends on plugins managed by OMF, consider renaming the script file to xx_a_script.fish
.
Similiarly, to make sure that a script runs before omf.fish
, you may prefix it with 00_
.
Alternatively, ~/.config/omf/before.init.fish
may be used.
Startup
Every time 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
script afterwards, which autoloads packages, themes and your custom init files.
For more information check the FAQ.
Dotfiles
The $OMF_CONFIG
directory 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 themebundle
- List of currently installed packages/themeschannel
- 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 startbefore.init.fish
- Custom script sourced before shell startkey_bindings.fish
- Custom key bindings where you can use thebind
command freely
Setting variables in init.fish
One of the most common startup commands used in init.fish
is 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/gocode
# Python developers otherwise
set -xg PYTHONDONTWRITEBYTECODE 1
About the bundle
Every time 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 get automatically installed, a package/theme removed from bundle isn't removed from user installation.
Older fish versions
In fish 2.2, there is no conf.d
directory, 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.fish
file instead of ~/.config/fish/config.fish
, as this allows you to keep the whole $OMF_CONFIG
directory under version control.
If you need startup commands to be run before Oh My Fish begins loading plugins, place them in before.init.fish
instead. If you're unsure, it is usually best to put things in 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.