One stop shop for command line help.
Project description
Halp
Halp is a command line tool that reminds you how to use your custom shell commands. It finds aliases and functions from your dotfiles and indexes them so you can query them later. Simply type halp <command>
to see what it does or halp --list
to see all your custom commands.
Point Halp at the appropriate dotfiles and it will index all your custom commands and add them to categories you specify. Then you can query it to find your commands and their usage.
Key features:
- Understands your aliases, functions, and exported environment variables
- Customizable categories
- Customizable regexes for matching commands
- Uses a SQLite database for fast querying
- Explains builtin commands with TLDR pages
- Explains builtin commands with options from mankier.com
Note: To enable TLDR integration, you must have a TLDR client installed and in your PATH. I recommend TealDeer
Usage
Remind yourself what a command does (Your own aliases and functions or TLDR pages)
halp <command>
See full output of a command
halp --full <command>
List all your custom commands
halp --list
View all commands in a particular category
halp --category <category>
Index your dotfiles
halp --index
Hide a command that you don't want to see
halp --hide <command ID>
Edit the configuration file
halp --edit-config
Search for commands who's code matches a regex pattern
halp --search-code <regex pattern>
See all options
halp --help
Installation
Note: Halp requires Python 3.10 or higher.
pipx is strongly recommended for installing Halp
pipx install halper
If pipx is not an option, you can install Halp in your Python user directory.
python -m pip install --user halper
First run
Before you can use Halp, you must first
- Create a configuration file by running `halp --edit-config``.
- Index your commands. You can do this by running `halp --index``.
Known issues
- Does not associate comments with a command on the following line
- If your function is written with parentheses instead of curly braces, it will not be parsed. ie
func command() (some code)
- Does not resolve if statements. ie
if [ -n "$BASH_VERSION" ]; then
. Consequently, if a command is wrapped in an if statement, it will still be indexed. Use--hide
to hide unwanted commands. - Does not follow
source
or.
directives within files - Tested on Bash and ZSH files only. Dotfiles for other shells may not work as expected.
Configuration
On first run, a TOML configuration file will be created for you.
IMPORTANT: You must add at least one path to the file_globs
list and then run halp --index
. Otherwise, no commands will be indexed.
case_sensitive = false # Whether or not to match case sensitively with regexes
command_name_ignore_regex = '' # Exclude commands who's names match this regex
file_exclude_regex = '' # Exclude files who's paths match this regex
file_globs = [] # Globs to match files which will be indexed for commands
[categories] # Commands are matched against these categories
[categories.example]
name = "" # The name of the category
code_regex = '' # Regex to match within the code
comment_regex = '' # Regex to match a comment on the same line as an alias/function definition or a comment on the first line of a function
description = "" # The description of this category
command_name_regex = '' # Regex to match the name of the command
path_regex = '' # Regex to match the path of the file
Contributing
Setup: Once per project
- Install Python 3.11 and Poetry
- Clone this repository.
git clone https://some.url/to/the/package.git
- Install the Poetry environment with
poetry install
. - Activate your Poetry environment with
poetry shell
. - Install the pre-commit hooks with
pre-commit install --install-hooks
.
Developing
- This project follows the Conventional Commits standard to automate Semantic Versioning and Keep A Changelog with Commitizen.
- When you're ready to commit changes run
cz c
- When you're ready to commit changes run
- Run
poe
from within the development environment to print a list of Poe the Poet tasks available to run on this project. Common commands:poe lint
runs all linterspoe test
runs all tests with Pytest
- Run
poetry add {package}
from within the development environment to install a run time dependency and add it topyproject.toml
andpoetry.lock
. - Run
poetry remove {package}
from within the development environment to uninstall a run time dependency and remove it frompyproject.toml
andpoetry.lock
. - Run
poetry update
from within the development environment to upgrade all dependencies to the latest versions allowed bypyproject.toml
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.