[](https://badge.fury.io/py/halper)  [](https://github.com/natelandau/halp/actions/workflows/automated-tests.yml) [](https://codecov.io/gh/natelandau/halp)
# 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
- Uses your inline comments to describe your commands
- Customizable regexes for matching commands
- SQLite database used for fast querying
- Explains builtin commands with [TLDR pages](https://tldr.sh/)
- Explains builtin commands with options from [mankier.com](https://www.mankier.com/)
Note: To enable TLDR integration, you must have a TLDR client installed and in your PATH. I recommend [TealDeer](https://github.com/dbrgn/tealdeer)
## Usage
Remind yourself what a command does (Your own aliases and functions or TLDR pages)
```bash
halp <command>
```
See full output of a command
```bash
halp --full <command>
```
List all your custom commands
```bash
halp --list
```
View all commands in a particular category
```bash
halp --category <category>
```
Index your dotfiles
```bash
halp --index
```
Hide commands that you don't want to see
```bash
halp --hide <command ID>,<command ID>,...
```
Customize the description of a command
```bash
halp --description <command ID>
```
Edit the configuration file
```bash
halp --edit-config
```
Search for commands who's code matches a regex pattern
```bash
halp --search-code <regex pattern>
```
See all options
```bash
halp --help
```
## Installation
Note: Halp requires Python 3.10 or higher.
Install with [pipx](https://pipx.pypa.io/)
```bash
pipx install halper
```
If pipx is not an option, you can install Halp in your Python user directory.
```bash
python -m pip install --user halper
```
## First run
Before you can use Halp, you must first
1. Create a configuration file by running `halp --edit-config``.
2. 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.
```toml
case_sensitive = false # Whether or not to match case sensitively with regexes
command_name_ignore_regex = '' # Exclude commands who's names match this regex
comment_placement = "BEST" # Where you place comments to describe your code. One of "BEST", "ABOVE", "INLINE"
file_exclude_regex = '' # Exclude files who's paths match this regex
file_globs = [] # Absolute path globs to files to parse for commands
uncategorized_name = "uncategorized" # The name of the uncategorized category
[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
```
### How halp finds descriptions for commands
The `comment_placement` setting determines where Halp looks for comments to describe your commands. It can be one of the following: `BEST` (default), `ABOVE`, `INLINE`. When `BEST` is used, Halp will look for comments in both places and use the inline comment when both are found.
Here's how Halp looks for comments in each case:
```bash
# Description <------ Above
alias command='some code' # Description <------ Inline
# Description <------ Above
func command() {
# Description <------ Inline
some code
}
```
# Contributing
## Setup: Once per project
1. Install Python 3.11 and [Poetry](https://python-poetry.org)
2. Clone this repository. `git clone https://some.url/to/the/package.git`
3. Install the Poetry environment with `poetry install`.
4. Activate your Poetry environment with `poetry shell`.
5. Install the pre-commit hooks with `pre-commit install --install-hooks`.
## Developing
- This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard to automate [Semantic Versioning](https://semver.org/) and [Keep A Changelog](https://keepachangelog.com/) with [Commitizen](https://github.com/commitizen-tools/commitizen).
- When you're ready to commit changes run `cz c`
- Run `poe` from within the development environment to print a list of [Poe the Poet](https://github.com/nat-n/poethepoet) tasks available to run on this project. Common commands:
- `poe lint` runs all linters
- `poe test` runs all tests with Pytest
- Run `poetry add {package}` from within the development environment to install a run time dependency and add it to `pyproject.toml` and `poetry.lock`.
- Run `poetry remove {package}` from within the development environment to uninstall a run time dependency and remove it from `pyproject.toml` and `poetry.lock`.
- Run `poetry update` from within the development environment to upgrade all dependencies to the latest versions allowed by `pyproject.toml`.
Raw data
{
"_id": null,
"home_page": "https://github.com/natelandau/halp",
"name": "halper",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "bash,cli,dotfiles,shell,zsh",
"author": "Nate Landau",
"author_email": "github@natenate.org",
"download_url": "https://files.pythonhosted.org/packages/17/8c/c483022c2eedfebc9114943609b5f53ccb3883da8b2bdf86e88cbf28bec9/halper-1.0.2.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/halper)  [](https://github.com/natelandau/halp/actions/workflows/automated-tests.yml) [](https://codecov.io/gh/natelandau/halp)\n\n# Halp\n\nHalp 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.\n\nPoint 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.\n\nKey features:\n\n- Understands your aliases, functions, and exported environment variables\n- Customizable categories\n- Uses your inline comments to describe your commands\n- Customizable regexes for matching commands\n- SQLite database used for fast querying\n- Explains builtin commands with [TLDR pages](https://tldr.sh/)\n- Explains builtin commands with options from [mankier.com](https://www.mankier.com/)\n\nNote: To enable TLDR integration, you must have a TLDR client installed and in your PATH. I recommend [TealDeer](https://github.com/dbrgn/tealdeer)\n\n## Usage\n\nRemind yourself what a command does (Your own aliases and functions or TLDR pages)\n\n```bash\nhalp <command>\n```\n\nSee full output of a command\n\n```bash\nhalp --full <command>\n```\n\nList all your custom commands\n\n```bash\nhalp --list\n```\n\nView all commands in a particular category\n\n```bash\nhalp --category <category>\n```\n\nIndex your dotfiles\n\n```bash\nhalp --index\n```\n\nHide commands that you don't want to see\n\n```bash\nhalp --hide <command ID>,<command ID>,...\n```\n\nCustomize the description of a command\n\n```bash\nhalp --description <command ID>\n```\n\nEdit the configuration file\n\n```bash\nhalp --edit-config\n```\n\nSearch for commands who's code matches a regex pattern\n\n```bash\nhalp --search-code <regex pattern>\n```\n\nSee all options\n\n```bash\nhalp --help\n```\n\n## Installation\n\nNote: Halp requires Python 3.10 or higher.\n\nInstall with [pipx](https://pipx.pypa.io/)\n\n```bash\npipx install halper\n```\n\nIf pipx is not an option, you can install Halp in your Python user directory.\n\n```bash\npython -m pip install --user halper\n```\n\n## First run\n\nBefore you can use Halp, you must first\n\n1. Create a configuration file by running `halp --edit-config``.\n2. Index your commands. You can do this by running `halp --index``.\n\n## Known issues\n\n- Does not associate comments with a command on the following line\n- If your function is written with parentheses instead of curly braces, it will not be parsed. ie `func command() (some code)`\n- 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.\n- Does not follow `source` or `.` directives within files\n- Tested on Bash and ZSH files only. Dotfiles for other shells may not work as expected.\n\n## Configuration\n\nOn first run, a TOML configuration file will be created for you.\n\nIMPORTANT: You must add at least one path to the `file_globs` list and then run `halp --index`. Otherwise, no commands will be indexed.\n\n```toml\ncase_sensitive = false # Whether or not to match case sensitively with regexes\ncommand_name_ignore_regex = '' # Exclude commands who's names match this regex\ncomment_placement = \"BEST\" # Where you place comments to describe your code. One of \"BEST\", \"ABOVE\", \"INLINE\"\nfile_exclude_regex = '' # Exclude files who's paths match this regex\nfile_globs = [] # Absolute path globs to files to parse for commands\nuncategorized_name = \"uncategorized\" # The name of the uncategorized category\n\n[categories] # Commands are matched against these categories\n [categories.example]\n name = \"\" # The name of the category\n code_regex = '' # Regex to match within the code\n 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\n description = \"\" # The description of this category\n command_name_regex = '' # Regex to match the name of the command\n path_regex = '' # Regex to match the path of the file\n```\n\n### How halp finds descriptions for commands\n\nThe `comment_placement` setting determines where Halp looks for comments to describe your commands. It can be one of the following: `BEST` (default), `ABOVE`, `INLINE`. When `BEST` is used, Halp will look for comments in both places and use the inline comment when both are found.\n\nHere's how Halp looks for comments in each case:\n\n```bash\n\n# Description <------ Above\nalias command='some code' # Description <------ Inline\n\n# Description <------ Above\nfunc command() {\n # Description <------ Inline\n some code\n}\n```\n\n# Contributing\n\n## Setup: Once per project\n\n1. Install Python 3.11 and [Poetry](https://python-poetry.org)\n2. Clone this repository. `git clone https://some.url/to/the/package.git`\n3. Install the Poetry environment with `poetry install`.\n4. Activate your Poetry environment with `poetry shell`.\n5. Install the pre-commit hooks with `pre-commit install --install-hooks`.\n\n## Developing\n\n- This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard to automate [Semantic Versioning](https://semver.org/) and [Keep A Changelog](https://keepachangelog.com/) with [Commitizen](https://github.com/commitizen-tools/commitizen).\n - When you're ready to commit changes run `cz c`\n- Run `poe` from within the development environment to print a list of [Poe the Poet](https://github.com/nat-n/poethepoet) tasks available to run on this project. Common commands:\n - `poe lint` runs all linters\n - `poe test` runs all tests with Pytest\n- Run `poetry add {package}` from within the development environment to install a run time dependency and add it to `pyproject.toml` and `poetry.lock`.\n- Run `poetry remove {package}` from within the development environment to uninstall a run time dependency and remove it from `pyproject.toml` and `poetry.lock`.\n- Run `poetry update` from within the development environment to upgrade all dependencies to the latest versions allowed by `pyproject.toml`.\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "One stop shop for command line help.",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/natelandau/halp",
"Repository": "https://github.com/natelandau/halp"
},
"split_keywords": [
"bash",
"cli",
"dotfiles",
"shell",
"zsh"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ec2b87425a5ee7393dd17ef8a929cc5cb8163a2f63340a67f4ed5255feb1a6c7",
"md5": "0cc8c81fc96db2ed5734e4d76b97a696",
"sha256": "14d7b00a98165e8d2a746d95a67db68b6e0d7a5accdd0f1a507a1a42b46345a1"
},
"downloads": -1,
"filename": "halper-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0cc8c81fc96db2ed5734e4d76b97a696",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 45059,
"upload_time": "2024-02-13T23:27:42",
"upload_time_iso_8601": "2024-02-13T23:27:42.617593Z",
"url": "https://files.pythonhosted.org/packages/ec/2b/87425a5ee7393dd17ef8a929cc5cb8163a2f63340a67f4ed5255feb1a6c7/halper-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "178cc483022c2eedfebc9114943609b5f53ccb3883da8b2bdf86e88cbf28bec9",
"md5": "5dc76180508890b06976a0d9d6b09027",
"sha256": "e3a30daea6ab3d9ffa9042f1ae24dfb629aae8637f9e2e1118865f708ad2507b"
},
"downloads": -1,
"filename": "halper-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5dc76180508890b06976a0d9d6b09027",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 41037,
"upload_time": "2024-02-13T23:27:43",
"upload_time_iso_8601": "2024-02-13T23:27:43.779876Z",
"url": "https://files.pythonhosted.org/packages/17/8c/c483022c2eedfebc9114943609b5f53ccb3883da8b2bdf86e88cbf28bec9/halper-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-13 23:27:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "natelandau",
"github_project": "halp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "halper"
}
JSON
