xuchunyang / eshell-z

cd to frequent directory in eshell, Emacs port of https://github.com/rupa/z

eshell-z

Introduction

The eshell-z package is an Emacs port of z. It keeps track of where you’ve been and how many commands you invoke there, and provides a convenient way to jump to the directories you actually use. eshell-z and z can work together by sharing the same data file.

Table of Contents

• =eshell-z=
  • Introduction
  • Install
    • MELPA
    • Manually
  • Setup
  • Usage
  • Notations
    • Aging
    • Frecency
    • Common
  • Tab Completion
  • See also

Install

MELPA

After setting up MELPA as a repository, use M-x package-install eshell-z or your preferred method.

Manually

Add eshell-z to your load-path. Something like

(add-to-list 'load-path "path/to/eshell-z")

Setup

To use this package, add following code to your init.el or .emacs

(add-hook 'eshell-mode-hook
          (defun my-eshell-mode-hook ()
            (require 'eshell-z)))

Usage

~ $ z -h
usage: z [-chlrtx] [regex1 regex2 ... regexn]

    -c, --current        estrict matches to subdirectories of the current directory
    -h, --help           show a brief help message
    -l, --list           list only
    -r, --rank           match by rank only
    -t, --time           match by recent access only
    -x, --delete         remove the current directory from the datafile

examples:

    z foo         cd to most frecent dir matching foo
    z foo bar     cd to most frecent dir matching foo, then bar
    z -r foo      cd to highest ranked dir matching foo
    z -t foo      cd to most recently accessed dir matching foo
    z -l foo      list all dirs matching foo (by frecency)

Notations

NOTICE This section is copied from the manpage of z.

Aging

The rank of directories maintained by z undergoes aging based on a simple formula. The rank of each entry is incremented every time it is accessed. When the sum of ranks is over 9000, all ranks are multiplied by 0.99. Entries with a rank lower than 1 are forgotten.

Frecency

Frecency is a portmanteau of ‘recent’ and ‘frequency’. It is a weighted rank that depends on how often and how recently something occurred. As far as I know, Mozilla came up with the term.

To z, a directory that has low ranking but has been accessed recently will quickly have higher rank than a directory accessed frequently a long time ago.

Frecency is determined at runtime.

Common

When multiple directories match all queries, and they all have a common prefix, z will cd to the shortest matching directory, without regard to priority. This has been in effect, if undocumented, for quite some time, but should probably be configurable or reconsidered.

Tab Completion

z supports basic tab completion, press TAB to complete on options and directories. This is implemented with pcomplete.

See also

• rupa/z
• wting/autojump and coldnew/eshell-autojump

eshell-z's Issues

Release 0.3.3 (or 0.4.0)?

Hi @xuchunyang!

Is it possible that you could push a new release for eshell-z that contains the PR I made a couple months back (#10)? I use Guix to manage my Emacs packages now and it only bundles the stable releases of this package.

Thanks a lot!

Autocompletion on directories

In the readme, you say

z supports basic tab completion, press TAB to complete on options and directories.

Tab completion works for me on options, but not on directories.
e.g. if I am in ~ and type z week1 CR, z takes me to ~/projects/week1, but if I type z week1 TAB, nothing happens. Am I using the package correctly?

Integration with Eshell's own `cd =`?

If you type cd = in Eshell, it will show you a list of all the directories you've recently been to. If you type cd =foo, it will change to the most recently visited directory containing the word "foo".

I wonder if eshell-z could plug into this mechanism, by reordering the recent directories list used by cd = each time a command is invoked.

Error on first M-x eshell-z: let: Wrong type argument: hash-table-p, nil

The eshell-z doesn't handle the case that the hash table eshell-z-freq-dir-hash-table is not initialized.

I will try to fix it late in the day if I get some time.

Arithmetic range errors

Hi!

Running any command produces Arithmetic range errors.

Running GNU Emacs 25.0.50.1 (i686-pc-mingw32) of 2015-11-09 (on Windows).

.emacs.d:master*? λ pwd
d:/src/dotfiles-emacs/.emacs.d
.emacs.d:master*? λ 
Arithmetic range error: "truncate", 1447160081.509
.emacs.d:master*? λ echo 'hi xuchunyang!'
hi xuchunyang!
.emacs.d:master*? λ 
Arithmetic range error: "truncate", 1447160095.6
.emacs.d:master*? λ 

Here's a backtrace:

Debugger entered--Lisp error: (range-error "truncate" 1447159905.182)
  truncate(1447159905.182)
  eshell-z--add()
  run-hooks(eshell-post-command-hook)
  eval((run-hooks (quote eshell-post-command-hook)))
  eshell-do-eval((run-hooks (quote eshell-post-command-hook)) nil)
  eshell-do-eval((progn (quote nil) (quote nil) (run-hooks (quote eshell-post-command-hook))) nil)
  (let ((eshell-current-handles (quote [nil (nil . 0) (nil . 0)])) eshell-current-subjob-p) (eshell-do-eval (quote (progn (quote nil) (quote nil) (run-hooks (quote eshell-post-command-hook)))) nil))
  eval((let ((eshell-current-handles (quote [nil (nil . 0) (nil . 0)])) eshell-current-subjob-p) (eshell-do-eval (quote (progn (quote nil) (quote nil) (run-hooks (quote eshell-post-command-hook)))) nil)))
  eshell-do-eval((let ((eshell-current-handles (quote [nil (nil . 0) (nil . 0)])) eshell-current-subjob-p) (eshell-do-eval (quote (progn (quote nil) (quote nil) (run-hooks (quote eshell-post-command-hook)))) nil)))
  eshell-resume-eval()
  eshell-eval-command((let ((eshell-current-handles (quote [nil (nil . 0) (nil . 0)])) eshell-current-subjob-p) (eshell-do-eval (quote (progn (quote nil) (quote nil) (run-hooks (quote eshell-post-command-hook)))) nil)) "ls")
  eshell-send-input(nil)
  funcall-interactively(eshell-send-input nil)
  call-interactively(eshell-send-input nil nil)
  command-execute(eshell-send-input)

How can I help you resolve this?