oh-my-fish/CONTRIBUTING.md

Issues | Packages | Commit Messages | Code Style

Contributing

Thanks for taking the time to read this guide and please do contribute to Oh My Fish. This is an open initiative and everyone is welcome. 🤘

Issues

Please open an issue for bug reports / patches. Include your OS version, code examples, stack traces and everything you can to help you debug your problem.

If you have a new feature or large change in mind, please open a new issue with your suggestion to discuss the idea together.

Package Repositories

This is the repository for the core Oh My Fish framework and bootstrap installer.

If your issue is related to a specific package, we still may be able to help, but consider visiting that package's issue tracker first.

Commit Messages

• Use the present tense ("add awesome-package" not "added ...")

• Less than 72 characters or less for the first line of your commit.

• Use of emoji is definitely encouraged. 🍭

Code Style

These rules are not set in stone. Feel free to open an issue with suggestions and/or feedback.

Control Flow

Using if..else..end blocks is preferred.

if not set -q ENV_VARIABLE
  set -g ENV_VARIABLE 42
end

The following syntax is more concise, but arguably less transparent.

You still may use and / or statements if you consider if..else..then to be overkill.

set -q VAR; set -g VAR 42

Functions

Use named arguments -a:

function greet -a message
  echo "$message"
end

Use -d description fields:

function greet -a message -d "Display a greeting message"
  echo "$message"
end

fish does not have private functions, so in order to avoid polluting the global namespace, use a prefix based in the scope of your code. For example, if you are writing a ninja plugin using __ninja_function_name.

If you are writing a function inside another function, prefix the inner one with the parent's name.

function parent
  function parent_child
  end
end

Note that it's still possible to mimic private functions in fish by deleting the function before returning using functions -e function_name

function public_func
  function private_func
    # ...
    functions -e private_func
  end
end

Blocks

Blocks allow you to write code resembling macro expressions composed of smaller blocks without relying on variables.

Compare the following without blocks:

set -l colors green1 green2 green3
if test $error -ne 0
  set colors red1 red2 red3
end

for color in $colors
  printf "%s"(set_color $color)">"
end

and using blocks:

for color in (begin
  if test $error -ne 0
    and printf "%s\n" red1 red2 red3
    or printf "%s\n" green1 green2 green3
  end)
  printf "%s"(set_color $color)">"
end

The second example does not use a colors variable.