NAME

fish_add_path - add to the path

SYNOPSIS

fish_add_path path ...
fish_add_path [(-g | --global) | (-U | --universal) | (-P | --path)] [(-m | --move)] [(-a | --append) | (-p | --prepend)] [(-v | --verbose) | (-n | --dry-run)] PATHS ...

DESCRIPTION

fish_add_path is a simple way to add more directories to fish's PATH. It does this by adding the directories either to fish_user_paths or directly to PATH (if the --path switch is given).

It is (by default) safe to use fish_add_path in config.fish, or it can be used once, interactively, and the paths will stay in future because of universal variables. This is a "do what I mean" style command - it tries to do the right thing by default, and follow your lead on what you have already set up (e.g. by using a global fish_user_paths if you have that already). If you need more control, consider modifying the variable yourself.

Directories are normalized with realpath. Trailing slashes are ignored and relative paths are made absolute (but symlinks are not resolved). If a directory is already included, it is not added again and stays in the same place unless the --move switch is given.

Directories are added in the order they are given, and they are prepended to the path unless --append is given. If $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to PATH, so they still stay ahead of the system paths. If the --path option is used, the paths are appended/prepended to PATH directly, so this doesn't happen.

With --path, because PATH must be a global variable instead of a universal one, the changes won't persist, so those calls need to be stored in config.fish. This also applies to fish_user_paths if you make it global (for instance by passing --global).

If no directory is new, the variable (fish_user_paths or PATH) is not set again or otherwise modified, so variable handlers are not triggered.

If an argument is not an existing directory, fish_add_path ignores it.

OPTIONS

-a or --append: Add directories to the end of the variable.
-p or --prepend: Add directories to the front of the variable (this is the default).
-g or --global: Use a global fish_user_paths.
-U or --universal: Use a universal fish_user_paths - this is the default if it doesn't already exist.
-P or --path: Manipulate PATH directly.
-m or --move: Move already-included directories to the place they would be added - by default they would be left in place and not added again.
-v or --verbose: Print the set command used, and some more warnings, like when a path is skipped because it doesn't exist or is not a directory. Verbose mode is automatically enabled when fish_add_path is used interactively and the output goes to the terminal.
-n or --dry-run: Print the set command that would be used without executing it.
-h or --help: Displays help about using this command.

If --move is used, it may of course lead to the path swapping order, so you should be careful doing that in config.fish.

EXAMPLE

# I just installed mycoolthing and need to add it to the path to use it.
# It is at /opt/mycoolthing/bin/mycoolthing,
# so let's add the directory: /opt/mycoolthing/bin.
> fish_add_path /opt/mycoolthing/bin
# I want my ~/.local/bin to be checked first,
# even if it was already added.
> fish_add_path -m ~/.local/bin
# I prefer using a global fish_user_paths
# This isn't saved automatically, I need to add this to config.fish
# if I want it to stay.
> fish_add_path -g ~/.local/bin ~/.otherbin /usr/local/sbin
# I want to append to the entire $PATH because this directory contains fallbacks
# This needs --path/-P because otherwise it appends to $fish_user_paths,
# which is added to the front of $PATH.
> fish_add_path --append --path /opt/fallback/bin
# I want to add the bin/ directory of my current $PWD (say /home/nemo/)
# -v/--verbose shows what fish_add_path did.
> fish_add_path -v bin/
set fish_user_paths /home/nemo/bin /usr/bin /home/nemo/.local/bin
# I have installed ruby via homebrew
> fish_add_path /usr/local/opt/ruby/bin

COPYRIGHT

2024, fish-shell developers