> La documentación de Oh My Fish • También disponible en
> <a href="../en-US/FAQ.md">🇺🇸</a>
> <a href="../ru-RU/FAQ.md">🇷🇺</a>
> <a href="../zh-CN/FAQ.md">🇨🇳</a>
> <a href="../uk-UA/FAQ.md">🇺🇦</a>
> <a href="../pt-BR/FAQ.md">🇧🇷</a>
<br>
Gracias por dedicar tiempo para leer este apartado de preguntas frecuentes (FAQ). Siéntete libre de crear un nuevo _issue_ si su pregunta no está respondida
en este documento.
## ¿Qué es Oh My Fish y por qué lo quiero?
Oh My Fish es un _framework_ para [Fishshell](http://fishshell.com/). Le ayudará a gestionar su configuración, los temas y paquetes.
## ¿Qué necesito conocer para utilizar Oh My Fish?
_Nada_. Puede instalar Oh My Fish y seguir utilizando Fish de manera normal. Cuando este listo para aprender más simplemente escriba en la línea de comandos `omf help`.
## ¿Qué son los paquetes Oh My Fish?
Los paquetes Oh My Fish son temas o complementos esdcitor en fish que expanden las funcionalidades principales de la _shell_, ejecutan código durante la
inicialización, añaden auto completado para las utilidades más conocidas, etc.
## ¿Qué tipos de paquetes Oh My Fish existen?
Existen aproximadamente 3 tipos de paquetes:
1. Utilidades de configuración. Por ejemplo [`pkg-pyenv`](https://github.com/oh-my-fish/pkg-pyenv) comprueba si `pyenv` existe en su sistema y ejecuta
`(pyenv init - | psub)` por usted durante el arranque.
2. Temas. Echa un vistazo a nuestra [galería de temas](https://github.com/oh-my-fish).
3. Utilidades tradicionales para la _shell_. Por ejemplo [`pkg-copy`](https://github.com/oh-my-fish/pkg-copy), una utilidad de portapapeles compatible con
sistemas Linux and OSX.
## ¿Qué hace Oh My Fish exactamente?
+ Ejecuta `$OMF_CONFIG/before.init.fish` si está disponible.
+ Carga de manera automática los paquetes y temas instalados en la ruta `$OMF_PATH/`.
+ Carga de manera automática su ruta de configuración. `~/.config/omf` de manera predeterminada, pero configurable mediante `$OMF_CONFIG`.
+ Carga de manera automática cualquier directorio `functions` de las rutas `$OMF_PATH` y `$OMF_CONFIG`
+ Ejecuta `$OMF_CONFIG/init.fish` si está disponible.
## ¿Cómo puedo actualizar una instalación de Oh My Fish ya existente?
> :warning: Recuerde realizar primero una copia de seguridad de sus archivos de configuración (o _dotfiles_) y otros datos importantes.
```
curl -L github.com/oh-my-fish/oh-my-fish/raw/master/bin/install | sh
```
Ahora puede eliminar con seguridad `$fish_path`.
```fish
rm -rf "$fish_path"
```
## ¿Cómo utilizo fish como mi _shell_ predeterminada?
> Oh My Fish Documentation • Also in
> <a href="../ru-RU/Packages.md">🇷🇺</a>
> <a href="../zh-CN/Packages.md">🇨🇳</a>
> <a href="../uk-UA/Packages.md">🇺🇦</a>
> <a href="../pt-BR/Packages.md">🇧🇷</a>
<br>
# Creating
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 plugin hello_world
```
> Use `omf new theme my_theme_name` for themes.
The utility changes the current directory to the newly created package:
```
$ ls -l
README.md
init.fish
functions/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 take care to provide it for your utilities when applicable.
`functions/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 under `functions` directory. This is required by fish autoloading mechanism, which loads functions on demand, avoiding loading unused functions at startup time.
Bear in mind that fish lacks a private scope, so if you need to split your package into functions, avoid name clashes prefixing your functions with something unique -- like your package name (e.g. `hello_world_print_help`). To avoid polluting command namespace, consider prefixing private functions with two underscores (e.g. `__function_name_print_help`).
# Hooks
Oh My Fish provides a "hooks" system that allows you to write scripts for your package that run when other interesting events occur. Packages can use these hooks to provide advanced installation, custom resource management, etc. Hooks are ordinary Fish scripts named after the event they are triggered by. Most hooks reside in a `hooks` directory inside a package's project directory.
>Hooks that are called at startup time (`init.fish` and `key_bindings.fish`) can slow down shell startup. Be sure to avoid slow code at startup time! Also, if your package doesn't need a hook file, be sure to remove it.
The working directory inside a hook is always set to the root directory of the package. The hooks Oh My Fish currently supports are listed below:
## `init`
The `init` hook is run once when the shell first loads. Scripts to handle this hook should be located at `init.fish` at package's root directory.
Inside this hook, you can access three package-related variables:
*`$package`: Package name
*`$path`: Package installation path
*`$dependencies`: Package dependencies
For example, with an `init.fish` script containing the following code:
```fish
echo "hello_world initialized"
```
you will see the line `hello_world initialized` at the top of the terminal when it is first opened.
Use this hook to modify the environment, load resources, autoload functions, etc. If your package does not export any function, you can still use this event to add functionality to your package, or dynamically create functions.
## `key_bindings`
If your package or theme need to use key bindings, be sure to set them up in the `key_bindings` hook. Key binding scripts must be located at `key_bindings.fish` at package's root directory. In this hook you can freely use the [`bind`][fish-bind] command to define custom key bindings.
>Themes can define key bindings too! Oh My Fish will reload key bindings when you switch themes.
## `install`
The `install` hook is triggered when a package is first installed. Scripts for this hook must be located at `hooks/install.fish`.
Inside this hook, you can access two package-related variables:
*`$package`: Package name
*`$path`: Package installation path
This hook is useful for downloading additional resources, setting up Git submodules, or installing third-party dependencies like Bash scripts.
## `update`
As you might have guessed, the `update` hook is triggered for a package after it is updated. Scripts for this hook must be located at `hooks/update.fish`.
Inside this hook, you can access two package-related variables:
*`$package`: Package name
*`$path`: Package installation path
This hook is useful for updating Git submodules or checking for new versions of third-party dependencies.
## `uninstall`
The `uninstall` hook will be triggered before a package is removed via `omf remove <pkg>`. Scripts for this hook must be located at `hooks/uninstall.fish`.
Inside this hook, you can access two package-related variables:
*`$package`: Package name
*`$path`: Package installation path
Packages can use this hook to clean up custom resources, etc.
> Note: for backwards-compatibility, uninstall hooks will also be run if they are located at `uninstall.fish` in the package root.
# Make it public
The official registry of public packages is managed in the [oh-my-fish/packages-main](https://github.com/oh-my-fish/packages-main) repository. See the README of that repository for instructions on how to add your package to the official package database.
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
> <a href="docs/ru-RU/README.md">🇷🇺</a>
> <a href="docs/zh-CN/README.md">🇨🇳</a>
> <a href="docs/uk-UA/README.md">🇺🇦</a>
> <a href="docs/pt-BR/README.md">🇧🇷</a>
<br>
## Table of contents
*[Installation](#installation)
*[Getting Started (command descriptions)](#getting-started)
*[Advanced](#advanced)
*[Startup](#startup)
*[Dotfiles](#dotfiles)
*[Creating Packages](#creating-packages)
## Installation
You can get started right away with the default setup by running this in your terminal:
```fish
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:
```fish
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](bin/install.sha256):
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's `default` theme features a right prompt, so it's necessary to use an alternative theme until a fix is released.
(see [#541](https://github.com/oh-my-fish/oh-my-fish/issues/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](#dotfiles).
#### `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](https://github.com/oh-my-fish/packages-main) 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](./docs/Themes.md) 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](/docs/en-US/Packages.md#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.
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-issues-new].
#### `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`](init.fish) script afterwards, which autoloads packages, themes and your custom init files.
For more information check the [FAQ](docs/en-US/FAQ.md#what-does-oh-my-fish-do-exactly).
### 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 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` is variables definition. Quite likely, such variables need to be available in any shell session. To achieve this, define them globally. For example:
```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` 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](docs/en-US/Packages.md) for more details.
