mirror of
https://github.com/oh-my-fish/oh-my-fish.git
synced 2024-11-25 09:41:40 +08:00
cfe8e769db
Refactor the installer to be more maintainable and interactive. The installer is now more robust and safe in its operation, and asks interactive questions for choices that the user must resolve. Setting up confuguration is also now changed to take advantage of Fish 2.3 features and does not mess with user's configuration files without permission. - Make installer smarter and use uninstaller in destroy - Better handling and checking for offline installs - `omf destroy` simply uses `install --uninstall` - Final warning message is no longer displayed when user intentionally aborts install - Backups are restored during uninstall - Update the README to detail the new ways to install OMF
150 lines
6.4 KiB
Markdown
150 lines
6.4 KiB
Markdown
<img src="https://cdn.rawgit.com/oh-my-fish/oh-my-fish/e4f1c2e0219a17e2c748b824004c8d0b38055c16/docs/logo.svg" align="left" width="192px" height="192px"/>
|
|
<img align="left" width="0" height="192px" hspace="10"/>
|
|
|
|
> The <a href="http://fishshell.com">Fishshell</a> Framework
|
|
|
|
[](/LICENSE.md) [](http://fishshell.com) [](https://travis-ci.org/oh-my-fish/oh-my-fish) [](https://oh-my-fish-slack.herokuapp.com)
|
|
|
|
|
|
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>
|
|
|
|
<br>
|
|
|
|
## Installation
|
|
|
|
You can get started right away with the default setup by running this in your terminal:
|
|
|
|
```fish
|
|
curl -L http://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 http://get.oh-my.fish > install
|
|
fish install --path=data/oh-my-fish --config=$HOME/.my-omf-config
|
|
```
|
|
|
|
You can also install Oh My Fish with Git or with an offline source tarball downloaded from the [releases page][releases]:
|
|
|
|
```fish
|
|
# 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 http://get.oh-my.fish > install
|
|
$ fish install --offline=omf.tar.gz
|
|
```
|
|
|
|
Run `install --help` for a complete list of install options you can customize.
|
|
|
|
## Getting Started
|
|
|
|
Oh My Fish includes a small utility `omf` to fetch and install new packages and themes.
|
|
|
|
#### `omf update` _`[omf]`_ _`[<package>...]`_
|
|
|
|
Update the framework and 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 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 pkg | theme` _`<name>`_
|
|
|
|
Scaffold out a new package or theme.
|
|
|
|
> This creates a new directory under `$OMF_CONFIG/{pkg | themes}/` with a template.
|
|
|
|
#### `omf search` _`-t|--theme / -pkg|--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 submit` _`pkg/<name>`_ _`[<url>]`_
|
|
|
|
Add a new package. To add a theme, use `omf submit` _`themes/<name>`_ _`<url>`_.
|
|
Please note that the _`[<url>]`_ portion of the command should be the url to your repo on github. For example, with the `example` plugin, the command run should be `omf submit pkg/example https://github.com/oh-my-fish/example`.
|
|
|
|
Make sure to [send us a PR][omf-pulls-link] to update the registry.
|
|
|
|
#### `omf doctor`
|
|
|
|
Use to troubleshoot before [opening an issue][omf-issues-new].
|
|
|
|
#### `omf destroy`
|
|
|
|
Uninstall Oh My Fish.
|
|
|
|
## Advanced
|
|
|
|
Oh My Fish installer places its startup code in your fish config file (`~/.config/fish/config.fish`).
|
|
|
|
### 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 are four important files:
|
|
|
|
- __`theme`__ - The current theme
|
|
- __`bundle`__ - List of currently installed packages/themes
|
|
- __`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
|
|
|
|
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`.
|
|
|
|
#### 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.
|
|
|
|
## 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.
|
|
|
|
|
|
[fishshell]: http://fishshell.com
|
|
[contributors]: https://github.com/oh-my-fish/oh-my-fish/graphs/contributors
|
|
[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls
|
|
[omf-issues-new]: https://github.com/oh-my-fish/oh-my-fish/issues/new
|
|
[releases]: https://github.com/oh-my-fish/oh-my-fish/releases
|