Skip to content

Latest commit

 

History

History
268 lines (196 loc) · 7.87 KB

README.md

File metadata and controls

268 lines (196 loc) · 7.87 KB
Raw

deer

Join the chat at https://gitter.im/Vifon/deer

DESCRIPTION

deer is a file navigator for zsh heavily inspired by ranger.

WHY

I've created deer because I really like to use ranger as an extension of my shell to quickly navigate the directories. Unfortunately, its startup time (even though short) is sometimes cumbersome. deer implements the very basic ranger-like file navigation + some basic operations on the commandline, like inserting the selected path (in various ways), which makes it fast to launch and ideal for the task. Not using the whole terminal can be viewed as an another feature.

Pros:

  • Launches much faster.
  • Better shell integration.
  • Retains the terminal contents and only uses a small part of the terminal.

Cons:

  • Offers only a small subset of ranger's features.
  • Needs zsh.

USAGE

To launch deer, press alt+k.

You can supply a numeric argument (alt-number) to go up the appropriate number of directory levels upon start.

If you activate deer with the cursor on a path, it will start in there.

KEYS AND FUNCTIONS

These functions can be bound custom keys (the default is in the parentheses):

  • down (j) -- One item down.
  • page_down (J) -- Five items down.
  • up (k) -- One item up.
  • page_up (K) -- Five items up.
  • enter (l) -- Enter the selected directory.
  • leave (h) -- Leave the current directory (one directory up).
  • next_parent (]) -- One item down in the left column.
  • prev_parent ([) -- One item up in the left column.
  • search (/) -- Select the first file matching the given pattern.
  • filter (f) -- Shows only files matching the given pattern.
  • toggle_hidden (H) -- Show/hide the hidden files.
  • quit (q) -- Exit deer.
  • append_path (a) -- Insert the current path and leave the cursor on its right.
  • append_abs_path (A) -- Absolute path version.
  • insert_path (i) -- Insert the current path and leave the cursor on its left.
  • insert_abs_path (I) -- Absolute path version.
  • multi_insert_dwim (s) -- Insert the current path, add a smart separator using the last character before the cursor (unless it's an opening brace, then use a comma), move the cursor down and don't quit yet.
  • multi_insert_abs (S) -- Insert the current absolute path and don't quit yet.
  • chdir (c) -- cd into the current directory and quit.
  • chdir_selected (C) -- cd into the selected directory and quit.
  • rifle (r) -- Run rifle(1) on the selected file.
  • edit (e) -- Run $EDITOR on the selected file (default to vim).

To bind a function to a different key, add something like this to your .zshrc:

typeset -Ag DEER_KEYS
DEER_KEYS[function]=key

The DEER_KEYS variable is an associative array holding the keys associated with functions. One function may be bound to only one key (meaning the previous one is overwritten).

INSTALLATION

First method

I assume you have ~/.fpath added to your $FPATH variable here. If you don't, either add it or use the second installation method. If you use some other directory, modify the commands below accordingly.

Copy the deer main file to ~/.fpath/deer and make sure it gets autoloaded in your zshrc:

autoload -U deer

Adding these lines will make the script available to the line editor, and bind it to alt+k respectively:

zle -N deer
bindkey '\ek' deer

Second method

Alternatively, you can directly source the file deer, and bind the initialization function to alt+k as follows:

source /path/to/deer.sh
zle -N deer
bindkey '\ek' deer

Third method

With a plugin manager. Tested with antigen, zgen and zplug:

  • antigen:
antigen bundle Vifon/deer
antigen apply
autoload -U deer
zle -N deer
bindkey '\ek' deer
  • zgen:
zgen load Vifon/deer
zgen save
autoload -U deer
zle -N deer
bindkey '\ek' deer
  • zplug:
zplug "vifon/deer", use:deer
zle -N deer
bindkey '\ek' deer

CONFIGURATION

By default, deer will use 22 lines of your terminal. This is configurable with the zstyle mechanism. Drop a line like this in zshrc to adjust this setting:

zstyle ':deer:' height 35

Show the hidden files by default:

zstyle :deer: show_hidden yes

To customize the keys used by deer, you may use the following code:

typeset -Ag DEER_KEYS   # Prepare the associative table.
DEER_KEYS[action_name]=key

Users of the Colemak keyboard layout may use the included colemak_keys.sh.example file to adjust the default keys to Colemak:

source colemak_keys.sh.example.

KNOWN ISSUES

These are the issues that I'm aware of, along with the reason for why I've decided not to fix them for now. If you think any of them is a dealbreaker, open a ticket on Github and I'll see what I can do.

Slashes are replaced with division slashes (U+2215) in file previews

This is an ugly workaround, and the issue is with the way the output is formatted (slash is used as a separator for paste(1) and column(1) as it cannot appear in the filename).

The ../ directory is not correctly shown when completing the previously typed path

The shown path is created by deleting the preexisting prefix from the absolute path. It greatly simplifies the code and makes it easier to maintain (it's already quite messy in some places).

Buggy behavior in the root directory (/)

The root directory handling is quite tricky as it's the only directory where going up and down does not keep you in the same directory. I've concluded that that directory itself is used very rarely and most of the bugs are not fatal.

FAQ

Can you add colors?

Unfortunately, no. It's a limitation of the underlying zle (zsh line editor) and I cannot do much about it.

Why are there so many strange features and their variations?

At first I add new features taylored for myself. Later I plan to review these features and clean them up. If you need something else, please leave a feature request or add it yourself if you know how.

The key binding system is ugly

Yes, it is. I plan to replace it with a proper keymap but for now it should suffice.

RELATED PROJECTS

lscd from the author of the original ranger is a minimal file browser written in a POSIX shell (with only a few necessary bashisms).

blscd is a Bash fork of lscd which is very similar to ranger.

SEE ALSO

ranger(1), zsh(1)

AUTHOR

Wojciech 'vifon' Siewierski < wojciech dot siewierski at gmail dot com >

COPYRIGHT

Copyright (C) 2014-2015 Wojciech Siewierski

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.