Contributing

Linting

The CI does a lint check on Markdown and YAML using Prettier with out-of-the-box settings and fish_indent on fish code. Therefore,

• if you are modifying any Markdown or Yaml files, run Prettier on the modified files
• if you are modifying fish code, run fish_indent on the modified .fish files
• you may want to just install a Prettier and Fish extension in your editor of choice to handle these tasks for you

...or your commits may not pass CI.

Code Conventions

Style Guide

• if > and or or
• test > [...]
• Long forms of flags > short forms
  • Use short form for frequently used commands such as set
  • Note that MacOS utils often do not support long flags, in which case one should use the short option for cross-platform compatibility
• Piping > command substitution
• variable names should be snake cased

Variables

• global variables that the user should not interact with should be prepended with _
• keep variables functionally scoped

Format

Fish code formatting is done via fish_indent, which is available as a VSCode plugin. Markdown and YAML formatting is done via Prettier, run with just the defaults.

Naming Conventions

All variables and functions should be named in snake_case. For variables and functions exposed to the user but not meant for the user to interact with, prepend an underscore in front of the name.

Testing

Dependencies

• jorgebucaran/fishtape - Runs Fish tests
• IlanCosman/clownfish - Mocks the behavior of commands

Run tests like so from the repository root

CI=true fishtape tests/**.fish

CI=true prevents config/fzf.fish and fzf_configure_bindings from being skipped.

Feature development

Before opening up a PR to add a new feature, first decide if it'll be a good fit. The best way is to read the Design Philosophy page, which includes the criteria for new features. If you did and you still think it's a good fit, then go for it. Just be sure to update the readme and add tests.