From 70727f441a364346d3981a45d36abaf8dfdf8140 Mon Sep 17 00:00:00 2001 From: Itzik Ephraim Date: Thu, 24 Aug 2017 10:45:49 +0300 Subject: [PATCH] README: Update Advanced information to fish 2.3+ Notes for fish 2.2 kept in a new subsection. --- README.md | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b21273c..66d1a7e 100644 --- a/README.md +++ b/README.md @@ -121,29 +121,39 @@ Uninstall Oh My Fish. ## Advanced -Oh My Fish installer places its startup code in your fish config file (`~/.config/fish/config.fish`). +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. +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: +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 -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`. - #### 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: @@ -160,6 +170,14 @@ set -xg PYTHONDONTWRITEBYTECODE 1 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.