{"id":16960737,"url":"https://github.com/descent098/ahd","last_synced_at":"2025-04-05T15:43:09.756Z","repository":{"id":38373477,"uuid":"236637664","full_name":"Descent098/ahd","owner":"Descent098","description":"Ad-hoc dispatcher; a system for creating ad-hoc macros","archived":false,"fork":false,"pushed_at":"2023-10-07T02:16:11.000Z","size":3865,"stargazers_count":0,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-15T02:36:38.292Z","etag":null,"topics":["cli","command-line-app","command-line-tool","command-line-utility","dispatcher","macro","macros","python","python-script","python3","utility","utility-application"],"latest_commit_sha":null,"homepage":"https://ahd.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Descent098.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":["Descent098"]}},"created_at":"2020-01-28T01:54:57.000Z","updated_at":"2022-05-19T15:39:41.000Z","dependencies_parsed_at":"2022-08-24T09:50:45.898Z","dependency_job_id":null,"html_url":"https://github.com/Descent098/ahd","commit_stats":{"total_commits":108,"total_committers":3,"mean_commits":36.0,"dds":0.01851851851851849,"last_synced_commit":"91b4ed20be73bc429ac928df7beee650ae61d526"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":"canadian-coding/python-package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Descent098%2Fahd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Descent098%2Fahd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Descent098%2Fahd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Descent098%2Fahd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Descent098","download_url":"https://codeload.github.com/Descent098/ahd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361598,"owners_count":20926642,"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":["cli","command-line-app","command-line-tool","command-line-utility","dispatcher","macro","macros","python","python-script","python3","utility","utility-application"],"created_at":"2024-10-13T22:49:56.327Z","updated_at":"2025-04-05T15:43:09.737Z","avatar_url":"https://github.com/Descent098.png","language":"Python","funding_links":["https://github.com/sponsors/Descent098"],"categories":[],"sub_categories":[],"readme":"![ahd-logo](https://raw.githubusercontent.com/Descent098/ahd/master/docs/img/ahd-logo.png) \n\n\n[![DeepSource](https://static.deepsource.io/deepsource-badge-light-mini.svg)](https://deepsource.io/gh/Descent098/ahd/?ref=repository-badge) \n\n\n[![Downloads](https://pepy.tech/badge/ahd)](https://pepy.tech/project/ahd)\n\n# Ad-Hoc Dispatcher\n\n*Create ad-hoc macros to be dispatched within their own namespace.*\n\n## Table of contents\n\n- [What does ahd do?](#what-does-ahd-do?)\n  - [Features \u0026 Roadmap](#features-\u0026-roadmap)\n    - [Path Expansion](#path-expansion)\n    - [Cross Platform](#cross-platform)\n    - [Dynamic Execution \u0026 Organization](#dynamic-execution-\u0026-organization)\n    - [Roadmap](#roadmap)\n  - [Example use cases](#example-use-cases)\n- [Why should I use ahd?](#why-should-I-use-ahd)\n- [Who is ahd for?](#who-is-ahd-for)\n- [Quick Start](#quick-start)\n  - [Dependencies](#dependencies)\n  - [Installation](#installation)\n    - [From PyPi](#from-pypi)\n    - [From Source](#from-source)\n  - [Usage](#usage)\n    - [Register](#register)\n    - [Using a Registered Command](#using-a-registered-command)\n    - [List](#list)\n    - [Docs](#docs)\n    - [Config](#config)\n- [Contact/Contribute](#contact/contribute)\n- [Glossary](https://ahd.readthedocs.io/en/latest/glossary/)\n\n## Additional Documentation\n\nThis readme will give you enough information to get up and running with ahd. If you are confused about terminology used then take a look at the [glossary section](#https://ahd.readthedocs.io/en/latest/glossary/) of the docs. If you are looking for more in-depth documentation:\n\n- Additional user and development/contribution documentation will be available at [https://ahd.readthedocs.io/en/latest/](https://ahd.readthedocs.io/en/latest/)\n- API documentation is available at [https://kieranwood.ca/ahd](https://kieranwood.ca/ahd)\n\n\n\n## What does ahd do? \n\nahd allows you to take annoying to remember commands and organize them into easy to re-use macros.\n\n## Features \u0026 Roadmap\n\n### Path Expansion\n\n- Macros can take full advantage of wildcards + regex to match directories. \nFor example if you wanted to delete all PDFs in all folders on the desktop you can use ```sudo ahd register no-pdfs \"rm *.pdf\" \"~/Desktop/*\"```.\n- *nix and windows path adages are cross-platform. For example ```~``` is converted to ```%USERPROFILE%``` on windows,  ```\\``` paths are converted to ```/``` on *nix systems and vice-versa.\n\n### Cross platform\n\n- ahd natively supports windows and any *nix systems (including Mac OS). \n- Supports copy-paste cross platform configurations (assuming the same commands and file structure are on both)\nFor example if you want to write a command that git pulls in a folder called ```/development``` on your desktop using the \\*nix standard ```~/Desktop/development/*``` works on both \\*nix and windows.\n\n### Dynamic Execution \u0026 Organization\n- One YAML file contains the configuration for all your macros instead of being all over the place.\n- Macros can be updated manually (editing the YAML file), or simply re-registered.\n- The defined Paths and commands can be overwritten on each use (see [overriding](https://ahd.readthedocs.io/en/latest/usage#overriding) for details).\n\n### Roadmap\n\nA full roadmap for each project version can be found here: https://github.com/Descent098/ahd/projects\n\n## Example use cases\n\nReally the possibilities are only limited to what you can type in your regular terminal, but here are some good examples:\n- Update every git repo in a directory\n- Organize your downloads folder by various filetypes\n- Multi-stage project compilation/build in various directories\n\n\n## Why should I use ahd?\n\nThe easiest way to understand why this project is useful is with an example. Let's say you want to write a simple script to take all the PDF's in a directory and put them in a ```.7z``` archive and then remove them. Well all you need is this simple command ```7za a -t7z PDFs.7z *.pdf \u0026\u0026 rm *.pdf```...\n\nYeah, pretty awful to remember. Assuming we want to do this every so often let's make a script we can call. Currently with bash you need to drop the script in ```usr/bin``` (and try to remember what you called it), or add it to your bash/fish/zsh aliases (assuming you use the alias file, or ```.bashrc``` etc. if you don't), and on windows it's just not even worth it.\n\nEnter ahd, you can register a macro (lets call it zip-pdfs) using the same annoying command, in this case ```sudo ahd register zip-pdfs \"7za a -t7z PDFs.7z *.pdf \u0026\u0026 rm *.pdf\" \".\"```. Now when we want to re-use this macro in the directory we're in you just type ```ahd zip-pdfs```. \n\nIf you forget the name there's a list command, and if you use a longer name there's bash autocomplete (fish and zsh support coming later).\n\n## Who is ahd for?\n\nThe primary audience is developers looking to speed up annoying workflows. However there are a number of other people it could benefit, such as:\n- devops specialists; can use ahd to create a common set of macros across servers .\n- dual booters; people who want one common config for multiple OS's.\n- testers; if you need to execute multiple tests on various systems you can write one macro to run them all.\n- etc; people who are sick of having a bunch of random scripts everywhere and want one config file for complex commands.\n\n\n## Quick-start\n\n### Dependencies\n\n- Python 3.6+ (or is at least only tested and officially supported for 3.6+)\n- pip for python\n\n\n\n### Installation\n\nOnce you have python3 and pip you have a few installation options.\n\n\n\n#### From Pypi\n\nRun ```pip install ahd``` or ```sudo pip3 install ahd``` (need a network connection)\n\n#### From source\n\n1. Clone this repo: (https://github.com/Descent098/ahd)\n2. Run ```pip install .``` or ```sudo pip3 install .```in the root directory (one with setup.py)\n\n\n\n### Usage\n\n```bash\nUsage: \n    ahd [-h] [-v]\n    ahd list [-l]\n    ahd docs [-a] [-o]\n    ahd config [-e] [-i CONFIG_FILE_PATH]\n    ahd register \u003cname\u003e [\u003ccommand\u003e] [\u003cpaths\u003e]\n    ahd \u003cname\u003e [\u003ccommand\u003e] [\u003cpaths\u003e] [-d]\n\nOptions:\n    -h, --help            show this help message and exit\n    -v, --version         show program's version number and exit\n    -l, --long            Shows all commands in configuration with paths and commands\n    -a, --api             shows the local API docs\n    -o, --offline         shows the local User docs instead of live ones\n    -e, --export          exports the configuration file\n    -i CONFIG_FILE_PATH, --import CONFIG_FILE_PATH \n                        imports the configuration file\n    -d, --details         prints the details of a command\n```\n\n#### Register\n\nThe register command allows you to register a command to be used later on. \n\n\u003cu\u003eRequired Arguments:\u003c/u\u003e\n\n- *\\\u003cname\\\u003e*;  This is a **positional** placeholder value for the name of a command you  are registering. Once the command is registered you can run it by using ```ahd \u003cname\u003e```.\n\n- *\\\u003ccommand\\\u003e*;  This is a **positional** placeholder value for the macro you want to run when the command is used after being registered. For example if you wanted to delete all the PDF's in a directory the macro you would normally run is ```rm *.pdf``` and so you would do ```ahd register \u003cname\u003e \"rm *.pdf\" \u003cpaths\u003e```. \n\n  It is generally advised to use encapsulating quotes since this avoids argument parsing artifacts.\n\n- *\\\u003cpaths\\\u003e*;  This is a **positional** placeholder value for the path(s) that you want the command to run the macro in by default. For example if you wanted to a command to execute a macro on the desktop when it's run you can do ```ahd register \u003cname\u003e \u003ccommand\u003e \"~/Desktop\"```.\n\n  It is generally advised to use encapsulating quotes since this avoids argument parsing artifacts. Additionally you can specify multiple directories through comma delimiting, for example: ```ahd register \u003cname\u003e \u003ccommand\u003e \"~/Desktop, ~/Documents, ~/Pictures\"```, or you can use **path expansion** which will match directories through regex or wildcards. For example to run a command in all directories **within** the desktop you could do ```ahd register \u003cname\u003e \u003ccommand\u003e \"~/Desktop/*\"``` or just use regex to match paths more explicitly for example to only include folders on the desktop that are numbers between 0-9 you could do: ```ahd register \u003cname\u003e \u003ccommand\u003e \"~/Desktop/[0-9]\"```.\n\n\n\n#### Using a Registered Command\n\nYou can use a registered command by simply typing ```ahd \u003cname\u003e```, where ```\u003cname\u003e``` is whatever name you gave to the command.\n\n\u003cu\u003eOptional Arguments:\u003c/u\u003e\n\n- *\\\u003ccommand\\\u003e*; This is an optional positional argument that lets you overwrite the command, while retaining the registered paths. For example lets say you have a set of paths registered with a command that typically runs ```git pull``` over the specified paths. You want to run a different command on the paths (lets say remove all the pdfs in the folder) You can do: ```ahd \u003cname\u003e \"rm *.pdf\"``` which will execute ```rm *.pdf``` instead of ```git pull``` on the defined paths.\n\n  It is generally advised to use encapsulating quotes since this avoids argument parsing artifacts.\n- *\\\u003cpaths\\\u003e*; This is an optional positional argument that lets you overwrite the paths the command will run against. To retain the original command you must use a \".\". So for example lets say you have a command registered that runs ```git pull``` against ```~/Desktop/*```, but now you want to run ```git pull``` against ```~/Documents/*``` you can use ```ahd \u003cname\u003e \".\" \"~/Documents/*\"``` and it will run the macro against ```~/Documents/*``` instead of ```~/Desktop/*```\n\n  It is generally advised to use encapsulating quotes since this avoids argument parsing artifacts. Additionally you can specify multiple directories through comma delimiting, for example: ```ahd register \u003cname\u003e \u003ccommand\u003e \"~/Desktop, ~/Documents, ~/Pictures\"```, or you can use **path expansion** which will match directories through regex or wildcards. For example to run a command in all directories **within** the desktop you could do ```ahd register \u003cname\u003e \u003ccommand\u003e \"~/Desktop/*\"``` or just use regex to match paths more explicitly for example to only include folders on the desktop that are numbers between 0-9 you could do: ```ahd register \u003cname\u003e \u003ccommand\u003e \"~/Desktop/[0-9]\"```.\n\n\n\n#### list\n\nThe list command shows a list of your current registered commands.\n\n\u003cu\u003eOptional Arguments:\u003c/u\u003e\n\n- *\\-l or \\-\\-long*: Shows all commands in configuration with the registered paths and macros.\n\n\n\n#### docs\n\nThe docs command is designed to bring up documentation as needed, you can run ```ahd docs``` to open the documentation site in the default browser.\n\n\n\n\u003cu\u003eOptional Arguments:\u003c/u\u003e\n\n- *\\-a or \\-\\-api*: Used to serve local API documentation (Not yet implemented)\n\n- *\\-o or \\-\\-offline*: Used to serve local user documentation (Not yet implemented)\n\n\n\n#### config\n\nThis command is used for configuration management. It is recomended to use [register](#register) to register/update commands. The config command is for managing configurations manually take a look at the documentation for details about [manual configuration](https://ahd.readthedocs.io/en/latest/usage#wildcards-and-cross-platform-paths).\n\n\n\n\u003cu\u003eOptional Arguments:\u003c/u\u003e\n\n  \\-e \\-\\-export: Export the current configuration file (called ```ahdconfig.yml```)\n\n  \\-i \\-\\-import: Import a configuration file; takes the path to the config file as an argument\n\n\n\n## Contact/Contribute\n\nFor a full contribution guide, check the [contribution section of the documentation](https://ahd.readthedocs.io/en/latest/contributing/). Also be sure to check the [faq](https://ahd.readthedocs.io/en/latest/faq/) before submitting issues.\n\nFor any additional questions please submit then through github [here](https://github.com/Descent098/ahd/issues/new?assignees=Descent098\u0026labels=documentation\u0026template=question.md\u0026title=%5Bquestion%5D) (much faster response), or my email [kieran@canadiancoding.ca](mailto:kieran@canadiancoding.ca?subject=AHD:Question).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdescent098%2Fahd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdescent098%2Fahd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdescent098%2Fahd/lists"}