{"id":15406756,"url":"https://github.com/dannyben/completely","last_synced_at":"2025-05-15T14:08:14.744Z","repository":{"id":39377080,"uuid":"387807244","full_name":"DannyBen/completely","owner":"DannyBen","description":"Generate bash completion scripts using a simple configuration file","archived":false,"fork":false,"pushed_at":"2025-04-11T11:27:51.000Z","size":232,"stargazers_count":115,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-15T14:08:11.389Z","etag":null,"topics":["bash","bash-completion","bash-completions","gem","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DannyBen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-20T13:50:58.000Z","updated_at":"2025-05-10T07:52:49.000Z","dependencies_parsed_at":"2023-12-16T08:42:30.250Z","dependency_job_id":"db1bc89c-5f53-4e48-b6df-0cdd554c86f1","html_url":"https://github.com/DannyBen/completely","commit_stats":{"total_commits":178,"total_committers":5,"mean_commits":35.6,"dds":0.0449438202247191,"last_synced_commit":"c413d319e9bf9f9b82e7caa8d3909825ed4cb40d"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fcompletely","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fcompletely/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fcompletely/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fcompletely/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DannyBen","download_url":"https://codeload.github.com/DannyBen/completely/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355335,"owners_count":22057354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-completion","bash-completions","gem","ruby"],"created_at":"2024-10-01T16:25:13.724Z","updated_at":"2025-05-15T14:08:12.867Z","avatar_url":"https://github.com/DannyBen.png","language":"Ruby","readme":"# Completely - Bash Completions Generator\n\n[![Gem Version](https://badge.fury.io/rb/completely.svg)](https://badge.fury.io/rb/completely)\n[![Build Status](https://github.com/DannyBen/completely/workflows/Test/badge.svg)](https://github.com/DannyBen/completely/actions?query=workflow%3ATest)\n[![Maintainability](https://api.codeclimate.com/v1/badges/6c021b8309ac796c3919/maintainability)](https://codeclimate.com/github/DannyBen/completely/maintainability)\n\n---\n\nCompletely is a command line utility and a Ruby library that lets you generate\nbash completion scripts from simple YAML configuration.\n\nThis tool is for you if:\n\n1. You develop your own command line tools.\n2. Your life feels empty without bash completions.\n3. Bash completion scripts seem overly complex to you.\n\nNote that if you are building bash command line scripts with [bashly][bashly],\nthen this functionality is already integrated with it.\n\n---\n\n\n## Install\n\n```bash\n$ gem install completely\n```\n\nor with homebrew:\n\n```bash\n$ brew install brew-gem\n$ brew gem install completely\n```\n\nor with Docker:\n\n```bash\n$ alias completely='docker run --rm -it --user $(id -u):$(id -g) --volume \"$PWD:/app\" dannyben/completely'\n```\n\n\n## Configuration syntax\n\nCompletely works with a simple YAML configuration file as input, and generates\na bash completions script as output.\n\nThe configuration file is built of blocks that look like this:\n\n```yaml\npattern:\n- --argument\n- --param\n- command\n```\n\nEach pattern contains an array of words (or functions) that will be suggested\nfor the auto complete process.\n\nYou can save a sample YAML file by running:\n\n```bash\n$ completely init\n```\n\nThis will generate a file named `completely.yaml` with this content:\n\n```yaml\nmygit:\n- -h\n- -v\n- --help\n- --version\n- init\n- status\n\nmygit init:\n- --bare\n- \u003cdirectory\u003e\n\nmygit status:\n- --help\n- --verbose\n- --branch\n- -b\n\nmygit status*--branch: \u0026branches\n- $(git branch --format='%(refname:short)' 2\u003e/dev/null)\n\nmygit status*-b: *branches\n```\n\nEach pattern in this configuration file will be checked against the user's\ninput, and if the input matches the pattern, the list that follows it will be\nsuggested as completions.\n\nNote that the suggested completions will not show flags (strings that start with \na hyphen `-`) unless the input ends with a hyphen.\n\nTo generate the bash script, simply run:\n\n```bash\n$ completely generate\n\n# or, to just preview it without saving:\n$ completely preview\n```\n\nFor more options (like setting input/output path), run:\n\n```bash\n$ completely --help\n```\n\n### Suggesting files, directories and other bash built-ins\n\nIn addition to specifying a simple array of completion words, you may use\nthe special syntax `\u003c..\u003e` to suggest more advanced functions.\n\n```yaml\npattern:\n- \u003cfile\u003e\n- \u003cdirectory\u003e\n```\n\nThese suggestions will add the list of files and directories\n(when `\u003cfile\u003e` is used) or just directories (when `\u003cdirectory\u003e` is used) to\nthe list of suggestions.\n\nYou may use any of the below keywords to add additional suggestions:\n\n| Keyword       | Meaning\n|---------------|---------------------\n| `\u003calias\u003e`     | Alias names\n| `\u003carrayvar\u003e`  | Array variable names\n| `\u003cbinding\u003e`   | Readline key binding names\n| `\u003cbuiltin\u003e`   | Names of shell builtin commands\n| `\u003ccommand\u003e`   | Command names\n| `\u003cdirectory\u003e` | Directory names\n| `\u003cdisabled\u003e`  | Names of disabled shell builtins\n| `\u003cenabled\u003e`   | Names of enabled shell builtins\n| `\u003cexport\u003e`    | Names of exported shell variables\n| `\u003cfile\u003e`      | File names\n| `\u003cfunction\u003e`  | Names of shell functions\n| `\u003cgroup\u003e`     | Group names\n| `\u003chelptopic\u003e` | Help topics as accepted by the help builtin\n| `\u003chostname\u003e`  | Hostnames, as taken from the file specified by the HOSTFILE shell variable\n| `\u003cjob\u003e`       | Job names\n| `\u003ckeyword\u003e`   | Shell reserved words\n| `\u003crunning\u003e`   | Names of running jobs\n| `\u003cservice\u003e`   | Service names\n| `\u003csignal\u003e`    | Signal names\n| `\u003cstopped\u003e`   | Names of stopped jobs\n| `\u003cuser\u003e`      | User names\n| `\u003cvariable\u003e`  | Names of all shell variables\n\nFor those interested in the technical details, any word between `\u003c...\u003e` will\nsimply be added using the [`compgen -A action`][compgen] function, so you can \nin fact use any of its supported arguments.\n\n### Suggesting custom dynamic suggestions\n\nYou can also use any command that outputs a whitespace-delimited list as a\nsuggestions list, by wrapping it in `$(..)`. For example, in order to add git\nbranches to your suggestions, use the following:\n\n```yaml\nmygit:\n- $(git branch --format='%(refname:short)' 2\u003e/dev/null)\n```\n\nThe `2\u003e /dev/null` is used so that if the command is executed in a directory\nwithout a git repository, it will still behave as expected.\n\n### Suggesting flag arguments\n\nAdding a `*` wildcard in the middle of a pattern can be useful for suggesting\narguments for flags. For example:\n\n```yaml\nmygit checkout:\n- --branch\n- -b\n\nmygit checkout*--branch:\n- $(git branch --format='%(refname:short)' 2\u003e/dev/null)\n\nmygit checkout*-b:\n- $(git branch --format='%(refname:short)' 2\u003e/dev/null)\n```\n\nThe above will suggest git branches for commands that end with `-b` or `--branch`.\nTo avoid code duplication, you may use YAML aliases, so the above can also be\nwritten like this:\n\n```yaml\nmygit checkout:\n- --branch\n- -b\n\nmygit checkout*--branch: \u0026branches\n- $(git branch --format='%(refname:short)' 2\u003e/dev/null)\n\nmygit checkout*-b: *branches\n```\n\n### Alternative nested syntax\n\nCompletely also supports an alternative nested syntax. You can generate this\nexample by running:\n\n```bash\n$ completely init --nested\n```\n\nThe example configuration below will generate the exact same script as the one\nshown at the beginning of this document.\n\n```yaml\nmygit:\n- -h\n- -v\n- --help\n- --version\n- init:\n  - --bare\n  - \u003cdirectory\u003e\n- status:\n  - --help\n  - --verbose\n  - +--branch: \u0026branches\n    - $(git branch --format='%(refname:short)' 2\u003e/dev/null)\n  - +-b: *branches\n```\n\nThe rules here are as follows:\n\n- Each pattern (e.g., `mygit`) can have a mixed array of strings and hashes.\n- Strings and hash keys (e.e., `--help` and `init` respectively) will be used\n  as completion strings for that pattern.\n- Hashes may contain a nested mixed array of the same structure.\n- When a hash is provided, the hash key will be appended to the parent prefix.\n  In the example above, the `init` hash will create the pattern `mygit init`.\n- In order to provide a wildcard (like `mygit status*--branch` in the standard\n  configuration syntax), you can provide either a `*` or a `+` prefix to the\n  hash key (e.g., `+--branch` or `\"*--branch\"`). Note that when using a `*`, \n  the hash key must be quoted since asterisks have special meaning in YAML.\n\n\n## Using the generated completion scripts\n\nIn order to enable the completions, simply source the generated script:\n\n```bash\n$ source completely.bash\n```\n\nIf you are satisfied with the result, and wish to copy the script to your bash\ncompletions directory, simply run:\n\n```bash\n$ completely install\n```\n\nAlternatively, you can copy the script manually to one of these directories\n(whichever exists):\n\n- `/usr/share/bash-completion/completions`\n- `/usr/local/etc/bash_completion.d`\n- `~/.local/share/bash-completion/completions`\n\n\n## Testing and debugging completion scripts\n\nYou can use the built in completions script tester by running `completely test`.\n\nThis command lets you test completions for your completions script.\n\nIn addition, you can set the `COMPLETELY_DEBUG` environment variable to any value\nin order to generate scripts with some additional debugging functionality. Run\n`completely generate --help` for additional information.\n\n\n## Using from within Ruby code\n\n```ruby\nrequire 'completely'\n\n# Load from file\ncompletions = Completely::Completions.load \"input.yaml\"\n\n# Or, from a hash\ninput = {\n  \"mygit\" =\u003e %w[--help --version status init commit],\n  \"mygit status\" =\u003e %w[--help --verbose --branch]\n}\ncompletions = Completely::Completions.new input\n\n# Generate the script\nputs completions.script\n\n# Or, generate a function that echos the script\nputs completions.wrapper_function\nputs completions.wrapper_function \"custom_function_name\"\n\n# Or, test the completions with the Tester object\np completions.tester.test \"mygit status \"\n```\n\n\n## Completions in ZSH\n\nIf you are using Oh-My-Zsh, bash completions should already be enabled,\notherwise, you should enable completion by adding this to your `~/.zshrc`\n(if is it not already there):\n\n```bash\n# Load completion functions\nautoload -Uz +X compinit \u0026\u0026 compinit\nautoload -Uz +X bashcompinit \u0026\u0026 bashcompinit\n```\n\n## Customizing the `complete` command\n\nIn case you wish to customize the `complete` command call in the generated\nscript, you can do so by adding any additional flags to the `completely.yaml`\nconfiguration file using the special `completely_options` key. For example:\n\n```yaml\ncompletely_options:\n  complete_options: -o nosort\n```\n\n## Contributing / Support\n\nIf you experience any issue, have a question or a suggestion, or if you wish\nto contribute, feel free to [open an issue][issues].\n\n---\n\n[issues]: https://github.com/DannyBen/completely/issues\n[compgen]: https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html\n[bashly]: https://bashly.dannyb.co/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fcompletely","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannyben%2Fcompletely","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fcompletely/lists"}