{"id":16528344,"url":"https://github.com/adrieankhisbe/diractions","last_synced_at":"2025-03-16T19:31:26.446Z","repository":{"id":20435103,"uuid":"23711846","full_name":"AdrieanKhisbe/diractions","owner":"AdrieanKhisbe","description":"👨‍💻 Doing Anything, Anywhere, from Here [zsh] 🚏","archived":false,"fork":false,"pushed_at":"2024-07-22T07:21:33.000Z","size":204,"stargazers_count":32,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-12T17:39:02.239Z","etag":null,"topics":["hacktoberfest","navigation","shell","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/AdrieanKhisbe.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":"2014-09-05T17:26:15.000Z","updated_at":"2024-07-22T07:21:37.000Z","dependencies_parsed_at":"2024-07-16T16:27:46.184Z","dependency_job_id":null,"html_url":"https://github.com/AdrieanKhisbe/diractions","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrieanKhisbe%2Fdiractions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrieanKhisbe%2Fdiractions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrieanKhisbe%2Fdiractions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdrieanKhisbe%2Fdiractions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdrieanKhisbe","download_url":"https://codeload.github.com/AdrieanKhisbe/diractions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221667259,"owners_count":16860585,"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":["hacktoberfest","navigation","shell","zsh"],"created_at":"2024-10-11T17:39:42.956Z","updated_at":"2024-10-27T11:09:29.992Z","avatar_url":"https://github.com/AdrieanKhisbe.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"Zsh Diractions\n==============\n\n*Doing Anything, Anywhere, from here*\n\n[![Tag Version](https://img.shields.io/github/tag/AdrieanKhisbe/diractions.svg)](https://github.com/AdrieanKhisbe/diractions/tags)\n[![Build Status](https://img.shields.io/github/checks-status/AdrieanKhisbe/diractions/master)](https://github.com/AdrieanKhisbe/diractions/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Join the chat https://gitter.im/AdrieanKhisbe/diractions](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/AdrieanKhisbe/diractions)\n\n\n[![asciicast](https://asciinema.org/a/140889.png)](https://asciinema.org/a/140889)\n\n## Aim\nThe goal of this plugin is *directory indexing*, map a short logical/mnemotechnical name to directory to quickly access them, or perform action in them.\nThanks to **diraction** user can perform quick actions on its registered directory, `cd` into it, `ls` it, `git` it, running some command, or refering to them in any command with short variable to denote them.\n\n### Hello Diraction\nSuppose that I have a hypothetical `favdir` and `mydir` directories that i use a alot.\nHere are a simple scenario: you go in `favdir`, see what file there is then copy one in `mydir` using the variable.\nThen I check it has been copied to the directory with `mydir ls`, then go in one of mydir subdirectory.\n\n```sh\n[~]           \u003e\u003e favdir                  # jumping in diraction folder\n[~_favdir]    \u003e\u003e ls\n                 some-file\n[~_favdir]    \u003e\u003e cp some-file $_mydir    # using mydir as a variable\n[~_favdir]    \u003e\u003e mydir ls                # calling ls in mydir\n                 other-file some-file\n[~_favdir]    \u003e\u003e mydir /sub              # jumping in a sub directory of mydir\n[~_mydir/sub] \u003e\u003e favdir - git status     # run any command or alias\n                 ? someuntrackfile\n```\n\n\u003c!-- §todo: Add some other example, gif of example\n§see: ho to do them --\u003e\n\n*This is just a glimpse of what you can do, if you wanna see more [scroll down a bit](#Usage)*. Otherwise, go in the terminal and practice. completion is there to help you *:)*\n\n\u003c!-- §see: inner link document --\u003e\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n**Table of Contents**\n\n- [Zsh Diractions](#zsh-diractions)\n    - [Aim](#aim)\n        - [Hello Diraction](#hello-diraction)\n    - [Usage](#usage)\n        - [Define your own diractions](#define-your-own-diractions)\n        - [Use your _diraction_](#use-your-diraction)\n            - [(Sub)Commands](#subcommands)\n            - [Completion](#completion)\n        - [Others Diraction Global Commands](#others-diraction-global-commands)\n    - [Installation](#installation)\n    - [Configuration](#configuration)\n        - [Your Diractions](#your-diractions)\n            - [The Diraction Config file](#the-diraction-config-file)\n            - [The custom hook](#the-custom-hook)\n        - [Customs](#customs)\n    - [History](#history)\n        - [Changelog](#changelog)\n    - [Notes](#notes)\n        - [Security Note](#security-note)\n\n\u003c!-- markdown-toc end --\u003e\n\n\n## Usage\n\nHere is some more in depth description about how to use *Diractions*.\n*Diraction* is both a function suite, and the function aliases and vars it will create for you.\n\n### Define your own diractions\nFirst step is to define your *diractions*, associate name to your most used directory.\n\n+ you simply create a new diraction with `diraction create \u003cname\u003e \u003cdirectory\u003e`\n  - by default it will check if directory exist\n  - to bypass this check use the `--ignore-missing-dir`\n  - to create the missing directories, use `--create-missing-dir`\n+ save the current directory with `diraction save \u003cname\u003e`\n+ you can also create many *diractions* with the `batch-create` command. it reads STDIN (so pipe a file to it, or use here docs) which can be usefull in configs.\n\n   ```sh\n   diraction batch-create \u003c\u003cDIRS\n   dir1 /long/dir/one\n   dir2 /long/dir/2\n   dir3 /long/dir with space\n   dir4 /some/dir # with a comment\n   DIRS\n   ```\n+ You can see the existing *diraction* using the following subcommands:\n  `list`(`ls`), `list-alias`(`la`), `list-dir`(`ld`) and even `grep` throught them\n\n### Use your _diraction_\n\nNow that you have a *diraction* it's time to use it. *:)*\nSimpliest way is to just type it's name to go in the attached directory.\nA better way is to type a subcommand along with it\n\n#### (Sub)Commands\nHere are the main commands. Commands that are executed in the context of the diraction:\n- `l`|`ls [args...]` : just some _ls_\n- `t`|`tree [args...]` : just some _tree_\n- `c`|`cd \u003csubdir\u003e` : jump in the subdirectory specified\n- `/ \u003csubdir\u003e` | `/\u003csubdir\u003e` : also jump in subdir\n- `o`|`open [filename]` : open folder (or file/subfolder being relative to the diraction folder)\n- `ed`|`edit \u003cfilename\u003e` : edit the file (being relative to the diraction folder)\n- `e`|`exec \u003cyour quoted command\u003e` : exec the command (use single quote for the variable to be evaluated)\n  - `-`|`,`|`_` : use the following as a command\n  - `--`|`,,`|`quoted-exec` : use the following as a command, preserving quotes. (only supported for zsh\u003e=5.3)\n- `i`|`interactive`|`prompt`|`shell` : to run several command in the context of the diraction directory\n- `w`|`where`|`?` : to be remind what is the diraction folder\n- all other commands contained in the `DIRACTION_DISPATCH_WHITELIST`.\n  by default `make` `rake` `sbt` `gradle` `git` `cask` `bundler` `ncdu` `du` `nemo` `nautilus` `open` `xdg-open` `ls`\n\nYou can also use the diraction variable in any command. `$_mydir` will be expanded to the attached directory.\n\nA word about how *diraction* works: the *diraction* aliases you create point to a *\"dispatch function\"*  taking the attached directory as first argument.\n(For instance *diraction* `mydir` pointing to `/tmp/mydir`is an alias for `_diraction-dispatch \"/tmp/mydir\"` )\n\n#### Completion\n\n*diraction* aliases support completion.\n\nCompletion cover:\n- the available subcommands described in previous section\n  - _ex_: `mydir l \u003cTAB\u003e` would complet to `ls` and all whitelisted command starting with a l.\n- the subfolder when subcommand start with a leading `/`\n  - _ex_: `mydir /ho \u003cTAB\u003e` would complete to dir such as `/home` `/hope` `ahola`\n  - _ex_: `mydir /home/ \u003cTAB\u003e` would complete to all dir in `$_mydir/home`\n  - note that fuzzy matching is performed on the last segment of the path\n- the nested subfolder when subcommand start with a `//`\n  - _ex_: `mydir //ho \u003cTAB\u003e` would complete subdir of `/home` `/hope` `ahola` up to 2 deep level (`$_mydir/home`, `$_mydir/home/personal` `$_mydir/home/personal/secretproject'`)\n  - _ex_: `mydir //home/ \u003cTAB\u003e` would complete to all subdir in `$_mydir/home` up to\n- the argument of the subcommand that was specified:\n  - _ex_: `mydir make \u003cTAB\u003e` would complete to `make` target\n  - _ex_: `mydir ls -\u003cTAB\u003e` would complete to `ls` options\n\n### Others Diraction Global Commands\n\n- `diraction disable \u003cdirname\u003e` : disable attached alias\n- `diraction enable \u003cdirname\u003e` : reenable it\n- `diraction destroy \u003cdirname\u003e` : destroy the alias.\n- `diraction destroy-all` : destroy all the existing diractions, need a `-f`, `--force` argument\n- `diraction reset` : destroy the diraction and reload them from the configuration\n\nand of course, the `help` command.\n\nBesides *every* `diraction` commands accept a `-h`, `--help` flag that will get you print help\nfor the specified command.\n\n## Installation\n\nIf you use package manager, (*which I recommend :)*),\njust add the plugin with `adrieankhisbe/diractions` identifier:\n\n- for [antibody](https://github.com/getantibody/antibody), add `antibody bundle \"adrieankhisbe/diractions\"`\n- for [antigen](https://github.com/zsh-users/antigen), add `antigen bundle adrieankhisbe/diractions`\n- for [zplug](https://github.com/zplug/zplug), add `zplug \"adrieankhisbe/diractions\"`\n\nIf you want to use the source directly you need to source [`diractions.plugin.zsh`](./diractions.plugin.zsh),\nto support completion you need to add the directory to `fpath` so that `__diraction-dispatch` `_diraction` are in it.\n\n## Configuration\n\n### Your Diractions\n*Diractions* are not meant to be defined by hand each time, of course there is ways to persist your diractions.\n\nThis can be done in two way:\n\n#### The Diraction Config file\n\nYou can store your *diraction* definition in the `DIRACTION_DEF_FILE` which is `~/.diractions` by default.\nIt just consist in a file having on each line two fields, the name of the diractions, then it's dir\nYou can put comments if you want, shell style `#`, and use environment variables `$HOME` or diractions variables `$_somepreviouslydefineddir`\n\nHere is some sample\n```sh\n  # here are some diraction definition\n  ssp  /some/stupid/path\n  yasp \"$_ssp/yet/another/stupid/path\"\n```\n\n\u003c!-- ##### Checkying the config --\u003e\nYou can check your definition file is correct by using the `diraction check config` command\n\n#### The custom hook\n\nAnother to customize diractions is to define a function named `diraction-personal-config`.\n\nThis functions is executed by the `diraction-load-config` if it exists.\nDefinitions in the function will take precedence\n\nHere is some Example:\n\n```zsh\n    diraction-personal-config (){\n    # put your config here\n    diraction-batch-create \u003c\u003cDIRS\n        dir1  /my/path/number1\n        yasp  /yet/another/stupid/path\n    DIRS\n   }\n```\n\n### Customs\nThere is also some variables to customize the behavior of diraction to fit your needs.\n\nHere are the main ones:\n- `DIRACTION_AUTO_CONFIG` : is the config automaticaly loaded after loading of plugin, true by default\n- `DIRACTION_DEF_FILE` : the name of the file containing your diraction definition\n- `DIRACTION_EDITOR` : which editor command is used for the edit command\n- `DIRACTION_INTERACTIVE_PROMPT` : the \"prompt\" for the \"interactive\" command\n- `DIRACTION_EXPORT_VARIABLES` :\n  - whether the `_dir` variables should be exported to the child processes.\n  - Off by default, can be activated setting variable to `true`\n  - note: this was the original _(only)_ behavior for versions prior to `v0.18.0`\n- `DIRACTION_READONLY_VARIABLES` : whether the `_dir` variables should be made read only. Deactivated by default, activate with `true`\n\n## History\n\nThis plugins started out as some growing *tweak* in my zsh personal config.\nFirst it was named *alvar*. (as a compaction of alias and variable) It just created an alias to jump in some dir, and a variable to refer to the directory. Later it was extended to perform some action in these directories.\nThen it was then extracted into is own repo, hence the troubled initial history.\nWith a new repo, he got a new name **Diractions** (*never explain an overobvious pun*),\nand is growing ever since with new functionalities. :)\n\n\u003c!-- Maybe list of feature introduced after 1 will go there? --\u003e\n\n\u003c!-- §TODO contribution note --\u003e\n\n\u003c!-- Maybe: add version? --\u003e\n\n\u003c!-- §maybe analytics? --\u003e\n\n### Changelog\n\nChangelog might be consulted in the dedicated [file](CHANGELOG.md)\n\n## License\nLicensed under [MIT](./LICENSE).\n\n## Notes\n\n**If you have any remark, refactor suggestion or you are having some unexpected behavior or bug (*soooory*), just post an issue ;)**\n\n### Security Note\n(I'm aware of the potential security issues: zsh env/function poisoinning, and evaluated code/injections,... but it's aimed to be used only in interactive mode on your shell so as insecure as a shell bash config.\nSo for now, I would advise not to use it without a glance of the source)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrieankhisbe%2Fdiractions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadrieankhisbe%2Fdiractions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrieankhisbe%2Fdiractions/lists"}