{"id":13394728,"url":"https://github.com/bbugyi200/funky","last_synced_at":"2025-05-16T06:07:13.451Z","repository":{"id":41309088,"uuid":"84404550","full_name":"bbugyi200/funky","owner":"bbugyi200","description":"Funky takes shell functions to the next level by making them easier to define, more flexible, and more interactive.","archived":false,"fork":false,"pushed_at":"2024-07-11T06:52:49.000Z","size":2175,"stargazers_count":654,"open_issues_count":24,"forks_count":19,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-16T04:21:52.183Z","etag":null,"topics":["aliases","bash","function","linux","shell","terminal","zsh"],"latest_commit_sha":null,"homepage":"","language":"Python","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/bbugyi200.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2017-03-09T06:05:40.000Z","updated_at":"2025-04-11T05:12:17.000Z","dependencies_parsed_at":"2024-10-25T10:17:06.203Z","dependency_job_id":"4304c286-8b5d-481f-b261-c6b3cf69a80f","html_url":"https://github.com/bbugyi200/funky","commit_stats":{"total_commits":601,"total_committers":4,"mean_commits":150.25,"dds":0.006655574043261225,"last_synced_commit":"26282cbf94d63aeae473de3751fa392a025bd170"},"previous_names":["bbugyi200/localalias"],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Ffunky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Ffunky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Ffunky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbugyi200%2Ffunky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbugyi200","download_url":"https://codeload.github.com/bbugyi200/funky/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478190,"owners_count":22077676,"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":["aliases","bash","function","linux","shell","terminal","zsh"],"created_at":"2024-07-30T17:01:29.684Z","updated_at":"2025-05-16T06:07:08.433Z","avatar_url":"https://github.com/bbugyi200.png","language":"Python","readme":"# funky [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Funky%20makes%20ZSH%20shell%20functions%20more%20powerful%20and%20easier%20to%20manage\u0026url=https://github.com/bbugyi200/funky\u0026via=bryan_bugyi\u0026hashtags=python,Linux,commandlineftw,developers)\n\n**Funky takes shell functions to the next level by making them easier to define, more flexible, and more interactive.**\n\n[![Project Version](https://img.shields.io/pypi/v/pyfunky)](https://pypi.org/project/pyfunky/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/pyfunky)](https://pypi.org/project/pyfunky/)\n[![Package Health](https://snyk.io/advisor/python/pyfunky/badge.svg)](https://snyk.io/advisor/python/pyfunky)\n\n[![Linter: pylint](https://img.shields.io/badge/linter-pylint-ffff00)](https://github.com/PyCQA/pylint)\n[![Linter: flake8](https://img.shields.io/badge/linter-flake8-008080)](https://github.com/PyCQA/flake8)\n[![Types: mypy](https://img.shields.io/badge/types-mypy-cd00cd)](https://github.com/python/mypy)\n[![Docstrings: pydocstyle](https://img.shields.io/badge/docstrings-pydocstyle-AFD3E6)](https://github.com/PyCQA/pydocstyle)\n[![Code Style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/imports-isort-ef8336)](https://github.com/PyCQA/isort)\n\n[![Test Workflow](https://github.com/bbugyi200/funky/actions/workflows/test.yml/badge.svg)](https://github.com/bbugyi200/funky/actions/workflows/test.yml)\n[![Lint Workflow](https://github.com/bbugyi200/funky/actions/workflows/lint.yml/badge.svg)](https://github.com/bbugyi200/funky/actions/workflows/lint.yml)\n[![Publish Workflow](https://github.com/bbugyi200/funky/actions/workflows/publish.yml/badge.svg)](https://github.com/bbugyi200/funky/actions/workflows/publish.yml)\n[![Coverage](https://codecov.io/gh/bbugyi200/funky/branch/master/graph/badge.svg)](https://codecov.io/gh/bbugyi200/funky)\n\n![demo]\n\n\n## Table of Contents\n\n* [Installation](#installation)\n   * [Using pipx to Install (preferred)](#using-pipx-to-install-preferred)\n   * [Using pip to Install](#using-pip-to-install)\n   * [Building from Source](#building-from-source)\n* [Usage](#usage)\n   * [Local vs Global](#local-vs-global)\n   * [Funk Definition Shortcuts](#funk-definition-shortcuts)\n      * [Special cd Funks](#special-cd-funks)\n      * [Simulate Shell Variables](#simulate-shell-variables)\n      * [The \"$@\" Special Parameter](#the--special-parameter)\n* [Articles / Blog Posts](#articles--blog-posts)\n* [Similar Projects](#similar-projects)\n* [Contributions](#contributions)\n\n\n## Installation\n\n### Using `pipx` to Install (preferred)\n\nThis package _could_ be installed using pip like any other Python package (in\nfact, see the section below this one for instructions). Given that we only need\nthis package's entry points (e.g. the `funky` command), however, we recommend\nthat [pipx] be used instead (replace `SHELL` with either `bash` or `zsh`):\n\n```shell\n# install and setup pipx\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n\n# install and setup funky\npipx install pyfunky\nfunky --setup-shell SHELL\n```\n\n[pipx]: https://github.com/pypa/pipx\n\n### Using `pip` to Install\n\nTo install funky using [pip], run the following commands in your terminal\n(replace `SHELL` with either `bash` or `zsh`):\n\n``` shell\npython3 -m pip install --user pyfunky  # install funky\nfunky --setup-shell SHELL  # hook funky into your shell\n```\n\nIf you don't have pip installed, this [Python installation guide] can guide\nyou through the process.\n\n[pip]: https://pip.pypa.io\n[Python installation guide]: http://docs.python-guide.org/en/latest/starting/installation/\n\n### Building from Source\n\nYou can either clone the public repository:\n\n``` shell\ngit clone git://github.com/bbugyi200/funky\n```\n\nOr download the [tarball]:\n\n``` shell\ncurl  -OL https://github.com/bbugyi200/funky/tarball/master\n```\n\nOnce you have a copy of the source, you can install funky by running:\n\n``` shell\nmake install\n```\n\nThe last thing you need to do is hook funky into your preferred shell, which\ncan be accomplished with the following command (replace `SHELL` with either\n`bash` or `zsh`):\n\n```shell\nfunky --setup-shell SHELL\n```\n\n\n## Usage\n\nFunks are manipulated using the `funky` and `gfunky` commands. These commands\nhave the same user interface. The difference between the two commands is\ntreated in the [Local vs Global](#local-vs-global) section.\n\n### Local vs Global\n\n**Local** funks are stored using a hidden database file that is located in the\nsame directory where the funk was created. These can be manipulated using the\noptions described in the demo above (run `funky -h` to see descriptions of\nthese options). Once created, a local funk can be used just like any other\ncommand or normal funk as long as you are inside of the directory where the\nlocal funk was originally defined.\n\n**Global** funks, on the other hand, are stored in your home directory\n(``/home/\u003cuser\u003e``) and can be used from any directory. Local funks can be used\nto override global funk definitions.\n\nLocal and global funks can be manipulated (created, removed, edited, renamed,\netc.) by using the ``funky`` and ``gfunky`` commands, respectively.\n\n### Funk Definition Shortcuts\n\nNormally when defining a funk, the provided raw definition (the final contents\nof the temp file) is inserted directly into the generated function definition.\nHowever, funky does try to make some alterations to the original funk\ndefinition when doing so is convenient. These *funky definition shortcuts* can\nmake defining funks faster:\n\n#### Special `cd` Funks\n\nA funk definition of the form `@./relative/path/to/directory` will be automatically changed to\n\n``` bash\ncd /absolute/path/to/directory/\"$@\" || return 1\n```\n\n#### Simulate Shell Variables\n\nA funk definition of the form `\"Some string here...\"` will be automatically changed to\n\n``` bash\necho \"Some string here...\" \"$@\"\n```\n\nThis allows you to use funks to simulate shell variables via [command substitution](https://www.gnu.org/software/bash/manual/html_node/Command-Substitution.html).\n\n#### The \"$@\" Special Parameter\n\nThis project originally used aliases. The decision to migrate to shell functions was made based on\nthe fact that shell functions are far more capable than aliases. Moreover, there is very little\nbenefit to using aliases over shell functions.\n\nWith that said, actual aliases do have one appeal over shell functions. When you use an alias, any\narguments that you pass to it are automatically passed to the command definition (at runtime,\naliases are just substituted with their definitions). For the purpose of emulating this behavior\nwhen it would typically be desired, a funk defined using a **single-line** command definition\nthat **does NOT already contain argument variables** (e.g. does not contain `$0`, `$1`, ...,\n`$9`, `$*`, or `$@`) will automatically have the `\"$@\"` special parameter appended to its\ndefinition. This allows for the same automatic argument handling that you would expect from an\nalias.\n\nSee the official [Bash docs] for more information on Bash's special parameters.\n\n[Bash docs]: https://www.gnu.org/software/bash/manual/html_node/Special-Parameters.html \n\n## Articles / Blog Posts\n\nWith the goal of listing alternative sources of documentation / tutorials, this\nsection will be used to track any articles or blog posts which mention funky:\n\n* [6 Command Line Tools for Productive Programmers](https://earthly.dev/blog/command-line-tools/#funky) (2021-07-23)\n\n\n## Similar Projects\n\n* [desk](https://github.com/jamesob/desk) - A lightweight workspace manager for the shell.\n* [smartcd](https://github.com/cxreg/smartcd) - Alter your bash (or zsh) environment as you cd.\n* [direnv](https://github.com/direnv/direnv) - is an extension for your shell. It augments existing shells with a new feature that can load and unload environment variables depending on the current directory.\n\n\n## Contributions\n\nPull requests are welcome. See [CONTRIBUTING.md](https://github.com/bbugyi200/funky/blob/master/CONTRIBUTING.md) for more information.\n\n[logo]: https://raw.githubusercontent.com/bbugyi200/funky/master/img/logo-96.png\n[travis]: https://travis-ci.org/bbugyi200/funky.svg?branch=master\n[codecov]: https://codecov.io/gh/bbugyi200/funky/branch/master/graph/badge.svg\n[demo]: https://raw.githubusercontent.com/bbugyi200/funky/master/img/demo.gif \"Funky Demonstration GIF\"\n[Github repo]: https://github.com/bbugyi200/funky\n[tarball]: https://github.com/bbugyi200/funky/tarball/master\n","funding_links":[],"categories":["Command-Line Productivity","Python","Shell"],"sub_categories":["PCAP"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbugyi200%2Ffunky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbugyi200%2Ffunky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbugyi200%2Ffunky/lists"}