Contributing to m-cli

Contributions are welcome and greatly appreciated! Whether it's a new feature, a bug fix, or documentation improvement, your help makes m-cli better for everyone.

Contribution Workflow

  1. Fork the repository on GitHub.

  2. Create a feature branch for your changes: 

    git checkout -b my-new-feature

  3. Make your changes. See the section below on how to add a new plugin.

  4. Commit your changes with a clear and descriptive message: 

    git commit -m 'Add some feature'

  5. Push your branch to your fork: 

    git push origin my-new-feature

  6. Open a Pull Request against the main branch of the original repository.

How to Add a New Plugin

The power of m-cli comes from its simple, file-based plugin system. Each executable file in the plugins/ directory is treated as a command.

To add a new command (e.g., m mycommand):

  1. Create a new executable file in the plugins/ directory named mycommand.

    touch plugins/mycommand
chmod +x plugins/mycommand

  2. The file should be a shell script starting with #!/usr/bin/env bash.

  3. Implement a help() function. This is crucial. The help output is parsed by the shell autocompletion scripts. It should clearly define the command's usage, description, and options.

  4. Parse the arguments passed to your script. A case statement is a common and effective way to do this.

Plugin Template

Here is a basic template to get you started:

#!/usr/bin/env bash

# This function provides the help text for your command.
# It is used for `m mycommand --help` and for generating autocompletions.
help(){
    cat<<__EOF__
Usage: m mycommand [OPTIONS]

Description: A brief description of what your command does.

Options:
  --help      Show this help message
  --an-option <value> An example option that takes a value
__EOF__
    exit 0
}

# Main script logic: parse the first argument.
case $1 in
    --help)
        help
        ;;
    --an-option)
        echo "You used --an-option with value: $2"
        ;;
    *)
        # If no valid option is given, show the help text and exit with an error.
        help && exit 1
        ;;
esac

Running Tests

The project includes a test suite located in the tests/ directory. These tests are written using the Bats testing framework. If you add a new feature, please consider adding a corresponding test file to ensure it works correctly and prevent future regressions.