= Diru * Introduction * Getting started * Client commands * Configuration * Practical usage = Introduction Diru is a Change Directory (cd) utility for augmenting Unix Shell functionality. Diru uses server/client architecture, which enables sharing of directory info between terminal sessions. Each Server serves one Project, which is a tree of related directories where user wants to jump around and which has a logical root. There can be multiple Servers, if user needs to access multiple Projects concurrently. Client queries directory info from Server and directory change is pushed to Shell in order to change the current directory within Shell. Diru is not able to change the Shell directory by itself. User must define a Shell function which can actually change the state of the Shell. Diru features: * Support for multiple concurrent Projects. * User and Project specific options (configuration). * Jump to Project root. * Find and jump to dir under Project root (regexp search). * Find and jump to dir under current dir (regexp search). * Fast directory search since Server maintains a memory image of directories. * Favorite directories in options (configuration), for permanent favorites. * Bookmark saving and referencing, for current favorites. * Directory change history and history referencing. * Scratch Pad for directory copy/paste. * Peer directory jumping, i.e. peer of current (regexp match). * Online help. = Getting started The first thing to do is to start Diru Hub. Hub is a server process that enables the Project specific Servers to be started. Hub will give each new Server an unique port to operate with, starting from Hub Port plus one. Start Hub to port 42323: shell> diru --hub --hport 42323 Start Server for a Project: shell> cd shell> diru --hport 42323 -s Server will be listening to port "42324" (HubPort + 1). Following Servers will get "42325", "42326" etc. Server displays the Port at startup. Server is a thread in Hub process. Servers can be started and killed at will. Complete list of running Servers can be seen with: shell> diru --hport 42323 -l When Server starts, it will detect the Project root. It can be a file or defined as environment variable. Environment variable DIRU_ROOT has higher precedence than the files. If ".diru_root_dir" file or a ".diru.yml" file is found from current dir or some dir above, the dir containing either of the files will become the Project root. If no files are found and DIRU_ROOT environment variable is not used, an error is issued. Client communicates with the Server in order to get and save directory info. As mentioned above, Diru is more or less useless unless user has defined a Shell function to realize directory changing. Here is an example of such function for Bourne Shell based shells: dr() { ret=`diru -p 42324 -c $*` if test $? -eq 0; then cd $ret fi } Diru Client command is called now "dr". We specify with "-p" that port "42324" is used towards the Server and with "-c" that we want to issue directory "change" commands. In practice only part of the commands will change directory, since some commands are only for queries. Directory is (and should be) changed if Diru returns 0. Otherwise Diru is performing a non-cd command, and Shell should just ignore the current Diru execution. If you want to see all Diru options, perform: shell> diru -h To jump to Project root, we do: shell> dr r If we want to jump to a subdir called "dir_0_0" (under root), we do: shell> dr r dir_0_0 Note that "dir_0_0" does not have to be directly under Project root, the directory is searched from the complete tree of directories under Project root using regexp matching. Now that we have changed directory for a couple of times, we can look at the directory change history: shell> dr h We can reference the history by listed numbers. In order to jump back to previous dir, we do: shell> dr h 0 = Client commands Client commands either change the current directory or query directory info from Server. Search commands: * "dr r" - change to Project root dir. * "dr r " - change to (somewhere) under Project root dir. * "dr t " - change to (somewhere) under current dir. Search can match to multiple directories. First match is used and the rest (Left-overs) are displayed to the user. Left-overs are also stored, and they can be referenced and used in order of appearance with simply issuing "dr". Search pattern can also be constructed from multiple pieces. shell> dr r dir 1_0_1 See "dr i" for alternatives for single letter commands. For example "r" can be replaced with "/". Bookmark commands: * "dr b" - display bookmarks. * "dr b ." - add current dir to bookmarks. * "dr b !" - reset (clear) bookmarks. * "dr b s " - store bookmarks to . * "dr b l " - load bookmarks from . * "dr b d " - delete bookmark with . * "dr b " - change dir to bookmark . History commands: * "dr h" - display history. * "dr h ." - add current dir to history. * "dr h !" - reset (clear) historys. * "dr h ," - reference last history item. * "dr h " - change dir to history . Scratch Pad commands: * "dr s ." - store current dir to Scratch Pad. * "dr s " - store to Scratch Pad. * "dr s" - change dir to Scratch Pad dir. Misc commands: * "dr p" - jump to peer dir, i.e. the peer of current (from options). * "dr c " - issue RPC command to server (reset etc., see below). * "dr f" - list favorites dirs (from options). * "dr f " - change dir to favorite . * "dr d m " - make directory. * "dr d r " - remove directory. * "dr i" - show command info. * "dr " - change to given dir (must be under current). * "dr" - change to next "Left-over" directory. RPC (Remote Procedure Call) commands: * "reset" - Reset Server state, i.e. History, Boorkmarks, Left-overs. * "abook" - Add current dir to Bookmarks. * "lbook" - List Bookmarks. * "rbook" - Reset Bookmarks. * "doc" - Show command documentation. * "dsync" - Synchronize Projecr dir content data with Server cache. * "sync" - Synchronize Options File content to Server. = Configuration Diru uses several environment variables, which are optional, and provides thereby backup values for non-specified command line info. * DIRU_HUB_PORT - Hub Port, if nothing, 41114 is used. * DIRU_PORT - Server Port, if nothing, ~/.diru.prt is used (Port File). * DIRU_OPTS - options file, if nothing, ~/.diru.yml is used. * DIRU_ROOT - Project root, used if ".diru_root_dir" and ".diru.yml" are missing. If Hub is started without "--hport" option, Diru checks if DIRU_HUB_PORT is defined. If not, port 41114 is used. If Client is used without "-p" option, Diru checks if DIRU_PORT is defined. If not, Port File, i.e. "~/.diru.prt", is used. Client does not work if no port info is given. If Server is started in a directory where (or above) a file called ".diru_root_dir" is found, then Project root is the directory containing ".diru_root_dir". If ".diru_root_dir" is not found, but ".diru.yml" is found, then Project root is the directory containing ".diru.yml", and Options for Project are taken from that file. Last resort for defining Project root, is DIRU_ROOT definition. If ".diru_root_dir" or DIRU_ROOT is used to define Project root, then DIRU_OPTS is used to define Options File. However, if not defined, then "~/.diru.yml" is used for options. An example Options file can be displayed with: shell> diru -t Available options in Options File: * :sync - Options File and Project directory hierarchy refresh period in seconds (for Server). * :dsync - Project directory hierarchy refresh period. This overrides ":sync" for Project updates (only). If value is 0, then no updates are done after initial update when Server starts. User might want to use 0, if the directory hierarhcy is big and/or does not change (often). * :hist - number of entries in history (max). * :favs - tagged favorite dirs. * :peers - , pairs for peer matching (String#sub method). = Practical usage After Hub has been started, user can start Server for each Project. Each Server runs on its own Port, and user can either define a Shell function for each Server with specific name, or define environment variable (DIRU_PORT) and change it according to Project. Depending on the usage pattern, user might as well want to use the Port File. Each Project could benefit from specific Options File, and thus user could mark the Project Root with ".diru.yml" and specify the Project setup there. Server caches all Project directory entries from disk to memory. This means that Client can quickly jump to any directory, even deep in the hierarchy. The target dir should be fairly accurately identified, otherwise the search results in too many Left-overs, which is impractical. Server updates the cache either peridically or only at start-up. User might prefer no automatic update, if the hierarchy is very large and extra load on disk is to be avoided. Cache update can be performed at will with an RPC call, "dsync". If user is working with a programming project, it is fairly common to have separate sub-directories for source code and build targets. Let's assume user starts with editing source code and has a terminal for accessing files. When program is ready for running, user opens a new terminal for handling the compile-run-debug iterations. User can copy source terminal directory to Scratch Pad. Then in the new terminal, user can refer to Scratch Pad and change to same directory as in source terminal. Finally user can change to a Peer of current dir, i.e. where program running and debugging takes place. If programming project is big enough, there might be several sub-dirs where source files reside. User might setup favorites to Options File, in order to easily reference the popular source code directories. For less permanent favorites, user can use Bookmarks. Options File can be edited while Server is running. Server reads the Options File every 5 seconds (configurable with ":sync") and refreshes its internal state. Server also updates its internal cache of Project directory content at each refresh cycle (by default). If ":dsync" Option is specified, it defines the "dsync" rate.