Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vifon/deer
ranger-like file navigation for zsh
https://github.com/vifon/deer
file-navigation ranger zsh
Last synced: about 1 month ago
JSON representation
ranger-like file navigation for zsh
- Host: GitHub
- URL: https://github.com/vifon/deer
- Owner: vifon
- Created: 2014-08-02T20:32:28.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2022-07-26T02:39:55.000Z (about 2 years ago)
- Last Synced: 2024-06-20T05:19:55.940Z (3 months ago)
- Topics: file-navigation, ranger, zsh
- Language: Shell
- Size: 106 KB
- Stars: 300
- Watchers: 10
- Forks: 14
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
deer
====[![Join the chat at https://gitter.im/Vifon/deer](https://badges.gitter.im/Vifon/deer.svg)](https://gitter.im/Vifon/deer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
DESCRIPTION
-----------`deer` is a file navigator for [zsh](http://zsh.sourceforge.net/)
heavily inspired by [ranger](http://ranger.nongnu.org/).**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`.[![](screenshots/2017-08-03-215440_640x364_scrot.png)](screenshots/2017-08-03-215440_640x364_scrot.png)
[![](screenshots/2017-08-03-215509_640x364_scrot.png)](screenshots/2017-08-03-215509_640x364_scrot.png)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](https://github.com/zsh-users/antigen),
[zgen](https://github.com/tarjoilija/zgen) and
[zplug](https://github.com/zplug/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](https://github.com/hut/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](https://github.com/D630/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 .