Zsh Diractions

Doing Anything, Anywhere, from here

Aim

The goal of this plugin is directory indexing, map a short logical/mnemotechnical name to directory to quickly access them, or perform action in them. Thanks 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.

Hello Diraction

Suppose that I have a hypothetical favdir and mydir directories that i use a alot. Here are a simple scenario: you go in favdir, see what file there is then copy one in mydir using the variable. Then I check it has been copied to the directory with mydir ls, then go in one of mydir subdirectory.

[~]           >> favdir                  # jumping in diraction folder
[~_favdir]    >> ls
                 some-file
[~_favdir]    >> cp some-file $_mydir    # using mydir as a variable
[~_favdir]    >> mydir ls                # calling ls in mydir
                 other-file some-file
[~_favdir]    >> mydir /sub              # jumping in a sub directory of mydir
[~_mydir/sub] >> favdir - git status     # run any command or alias
                 ? someuntrackfile

This is just a glimpse of what you can do, if you wanna see more scroll down a bit. Otherwise, go in the terminal and practice. completion is there to help you :)

Table of Contents

Zsh Diractions

Usage

Here is some more in depth description about how to use Diractions. Diraction is both a function suite, and the function aliases and vars it will create for you.

Define your own diractions

First step is to define your diractions, associate name to your most used directory.

you simply create a new diraction with diraction create <name> <directory>
by default it will check if directory exist
to bypass this check use the --ignore-missing-dir
to create the missing directories, use --create-missing-dir
save the current directory with diraction save <name>
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.

   diraction batch-create <<DIRS
   dir1 /long/dir/one
   dir2 /long/dir/2
   DIRS

You can see the existing diraction using the following subcommands: list(ls), list-alias(la), list-dir(ld) and even grep throught them

Use your diraction

Now that you have a diraction it's time to use it. :) Simpliest way is to just type it's name to go in the attached directory. A better way is to type a subcommand along with it

(Sub)Commands

Here are the main commands. Commands that are executed in the context of the diraction:

l|ls [args...] : just some ls
t|tree [args...] : just some tree
c|cd <subdir> : jump in the subdirectory specified
/ <subdir> | /<subdir> : also jump in subdir
o|open [filename] : open folder (or file/subfolder being relative to the diraction folder)
ed|edit <filename> : edit the file (being relative to the diraction folder)
e|exec <your quoted command> : exec the command (use single quote for the variable to be evaluated)
-|,|_ : use the following as a command
--|,,|quoted-exec : use the following as a command, preserving quotes. (only supported for zsh>=5.3)
i|interactive|prompt|shell : to run several command in the context of the diraction directory
w|where|? : to be remind what is the diraction folder
all other commands contained in the DIRACTION_DISPATCH_WHITELIST. by default make rake sbt gradle git cask bundler ncdu du nemo nautilus open xdg-open ls

You can also use the diraction variable in any command. $_mydir will be expanded to the attached directory.

A word about how diraction works: the diraction aliases you create point to a "dispatch function" taking the attached directory as first argument. (For instance diraction mydir pointing to /tmp/mydiris an alias for _diraction-dispatch "/tmp/mydir" )

Completion

diraction aliases support completion.

Completion cover:

the available subcommands described in previous section
ex: mydir l <TAB> would complet to ls and all whitelisted command starting with a l.
the subfolder when subcommand start with a leading /
ex: mydir /ho <TAB> would complete to dir such as /home /hope ahola
ex: mydir /home/ <TAB> would complete to all dir in $_mydir/home
note that fuzzy matching is performed on the last segment of the path
the nested subfolder when subcommand start with a //
ex: mydir //ho <TAB> would complete subdir of /home /hope ahola up to 2 deep level ($_mydir/home, $_mydir/home/personal $_mydir/home/personal/secretproject')
ex: mydir //home/ <TAB> would complete to all subdir in $_mydir/home up to
the argument of the subcommand that was specified:
ex: mydir make <TAB> would complete to make target
ex: mydir ls -<TAB> would complete to ls options

Others Diraction Global Commands

diraction disable <dirname> : disable attached alias
diraction enable <dirname> : reenable it
diraction destroy <dirname> : destroy the alias.
diraction destroy-all : destroy all the existing diractions, need a -f, --force argument
diraction reset : destroy the diraction and reload them from the configuration

and of course, the help command.

Besides every diraction commands accept a -h, --help flag that will get you print help for the specified command.

Installation

If you use package manager, (which I recommend :)), just add the plugin with adrieankhisbe/diractions identifier:

for antibody, add antibody bundle "adrieankhisbe/diractions"
for antigen, add antigen bundle adrieankhisbe/diractions
for zplug, add zplug "adrieankhisbe/diractions"

If you want to use the source directly you need to source diractions.plugin.zsh, to support completion you need to add the directory to fpath so that __diraction-dispatch _diraction are in it.

Configuration

Your Diractions

Diractions are not meant to be defined by hand each time, of course there is ways to persist your diractions.

This can be done in two way:

The Diraction Config file

You can store your diraction definition in the DIRACTION_DEF_FILE which is ~/.diractions by default. It just consist in a file having on each line two fields, the name of the diractions, then it's dir You can put comments if you want, shell style #, and use environment variables $HOME or diractions variables $_somepreviouslydefineddir

Here is some sample

  # here are some diraction definition
  ssp  /some/stupid/path
  yasp "$_ssp/yet/another/stupid/path"

You can check your definition file is correct by using the diraction check config command

The custom hook

Another to customize diractions is to define a function named diraction-personal-config.

This functions is executed by the diraction-load-config if it exists. Definitions in the function will take precedence

Here is some Example:

    diraction-personal-config (){
    # put your config here
    diraction-batch-create <<DIRS
        dir1  /my/path/number1
        yasp  /yet/another/stupid/path
    DIRS
   }

Customs

There is also some variables to customize the behavior of diraction to fit your needs.

Here are the main ones:

DIRACTION_AUTO_CONFIG : is the config automaticaly loaded after loading of plugin, true by default
DIRACTION_DEF_FILE : the name of the file containing your diraction definition
DIRACTION_EDITOR : which editor command is used for the edit command
DIRACTION_INTERACTIVE_PROMPT : the "prompt" for the "interactive" command
DIRACTION_EXPORT_VARIABLES :
whether the _dir variables should be exported to the child processes.
Off by default, can be activated setting variable to true
note: this was the original (only) behavior for versions prior to v0.18.0
DIRACTION_READONLY_VARIABLES : whether the _dir variables should be made read only. Deactivated by default, activate with true

History

This plugins started out as some growing tweak in my zsh personal config. First 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. Then it was then extracted into is own repo, hence the troubled initial history. With a new repo, he got a new name Diractions (never explain an overobvious pun), and is growing ever since with new functionalities. :)

Changelog

Changelog might be consulted in the dedicated file

License

Licensed under MIT.

Notes

If you have any remark, refactor suggestion or you are having some unexpected behavior or bug (soooory), just post an issue ;)

Security Note

(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. So for now, I would advise not to use it without a glance of the source)