Fish: Not able to load built-in functions when experimenting with subdirectories

Understanding Fish Function Loading

The Fish shell manages its environment differently than Bash or Zsh. In Bash, you might rely on the $PATH variable to find scripts, but Fish separates executables from functions. Functions in Fish are stored as individual .fish files located in specific directories. By default, Fish looks for these files in a few standard locations, such as /usr/share/fish/functions/ and $XDG_CONFIG_HOME/fish/functions/. It does not recursively search arbitrary subdirectories of your current working directory or other random paths unless you tell it to.

When you create a script inside a subdirectory and try to call a function defined within it, Fish throws an error like "Function not found" because it simply does not know where to look. This is a security and performance feature; loading every possible file in every subdirectory would be slow and potentially dangerous. You need to explicitly register the directory containing your custom functions.

Configuring the Function Path

To fix the issue, you need to modify the fish_function_path variable. This variable is a colon-separated list of directories that Fish scans for function definitions. Unlike $PATH, which uses spaces or colons depending on the OS, Fish uses colons consistently. You can view the current path by running:

echo $fish_function_path

You will likely see output similar to:

/home/user/.config/fish/functions:/usr/share/fish/functions

To add a new directory, such as ~/my_scripts/functions, you should use the universal mode setting so that the change persists across all terminal sessions. Run the following command, replacing the path with your actual directory:

set -U fish_function_path $fish_function_path ~/my_scripts/functions

This command appends your custom directory to the existing list. The -U flag saves the setting universally, meaning it will apply to all new Fish shells you open. After running this, restart your terminal or source your configuration with source ~/.config/fish/config.fish.

Organizing Your Custom Functions

Once the path is configured, you must ensure your function files are named correctly. Each function must reside in its own .fish file. For example, if you want to define a function called my_helper, you should create a file named my_helper.fish inside your designated directory. The content of the file should look like this:

function my_helper
    echo "Hello from my helper!"
end

Do not put multiple functions in a single file unless you are sure about the sourcing behavior, though typically one function per file is the cleanest approach for Fish. If you have many functions, consider creating a dedicated folder structure. For instance, you might have ~/fish_functions/cli_tools/ and add that entire folder to the fish_function_path.

If you are experimenting with subdirectories within a project, remember that Fish does not automatically load functions from the current directory. You must always add the parent directory of the .fish files to the fish_function_path. This prevents accidental execution of malicious or malformed functions from downloaded code.

Verifying the Configuration

After adding the directory, verify that Fish can see your functions by running:

functions --search

This command lists all available functions. Look for your custom function in the output. If it appears, the path is correctly configured. If it does not appear, double-check the spelling of the directory path and ensure the file has the correct extension (.fish). You can also check for syntax errors in your function file by running:

fish -c 'source /path/to/your/function.fish'

If there is a syntax error, Fish will report it here. Fixing syntax issues is often the reason why functions fail to load even when the path is correct.

Common Pitfalls and Troubleshooting

One common mistake is trying to use export to set the function path. In Fish, you should never export fish_function_path; it is an internal variable managed by the shell. Using set -x will cause unexpected behavior. Always use set -U for persistent changes or set -g for global scope within a session.

Another issue arises when users try to link functions dynamically. Fish loads functions at startup or when first referenced. If you modify a function file while a shell is running, you may need to reload the function manually using source /path/to/function.fish or restart the terminal. Fish does not watch for file changes automatically.

If you are migrating from Bash, note that Fish functions do not support all Bash-specific features. Stick to POSIX-compliant syntax within your functions to ensure compatibility. For more complex scripting tasks involving arrays, you might find resources on iterating arrays useful, such as those discussed in Iterating Arrays and Spaced String Pairs in Zsh: A Comprehensive Guide, although the syntax differs significantly between shells.

Frequently Asked Questions

Why doesn't Fish load functions from the current directory?

Fish intentionally avoids loading functions from the current directory to prevent security risks and performance issues. It only searches directories explicitly listed in the fish_function_path variable. You must manually add any directory containing your custom functions to this path.

How do I remove a directory from the function path?

You can remove a directory by editing the universal variable. Use set -U fish_function_path (string match -v /path/to/remove $fish_function_path). This command filters out the unwanted path and updates the configuration permanently.

Can I use symlinks in the function path?

Yes, Fish supports symlinks in the fish_function_path. If you point your function directory to a symlink, Fish will follow it and load the functions from the target location. This is useful for organizing functions across different projects.

What is the difference between -U and -g in set commands?

The -U flag sets a universal variable that persists across all sessions and applies to all users (if configured). The -g flag sets a global variable that lasts for the current user's session but is not saved to disk. Use -U for permanent configuration changes.

How do I debug a function that won't load?

Use fish -c 'source /path/to/file.fish' to check for syntax errors. Also, run functions --search to verify that Fish sees the function name. If the file has valid syntax but the function is missing, check that the directory is correctly added to fish_function_path.