Add zsh anything.el plugin
[zsh.git] / .zsh / zaw / README.rst
1 =================================
2 zaw - zsh anything.el-like widget
3 =================================
4
5 install
6 =======
7
8 ::
9
10 $ git clone git://github.com/zsh-users/zaw.git
11 remote: Counting objects: 136, done.
12 remote: Compressing objects: 100% (86/86), done.
13 remote: Total 136 (delta 43), reused 136 (delta 43)
14 Receiving objects: 100% (136/136), 23.68 KiB, done.
15 Resolving deltas: 100% (43/43), done.
16 $ echo "source ${PWD}/zaw/zaw.zsh" >> ~/.zshrc
17
18 and restart zsh or manualy source ``zaw.zsh``.
19
20
21 usage
22 =====
23
24 1. Trigger `zaw` by pressing ``Ctrl-x ;`` (``^x;``).
25 2. select `source` and press ``enter``.
26 3. filter items with zsh patterns separated by spaces, use ``^N``, ``^P`` and select one.
27 4. execute action by pressing enter key or press ``Meta-enter`` for alternative action.
28
29 instead, press tab key and select action you want to execute.
30
31
32 sources
33 =======
34
35 currently these sources are available:
36
37 - aliases
38 - applications
39 - bookmark
40 - cdr (needs cdr enabled. Google it or use `this packaged version <https://github.com/willghatch/zsh-cdr>`_)
41 - commands
42 - command-output
43 - fasd
44 - fasd-directories
45 - fasd-files
46 - functions
47 - git-branches
48 - git-recent-all-branches
49 - git-recent-branches
50 - git-files
51 - git-files-legacy
52 - git-log
53 - git-reflog
54 - git-status
55 - history
56 - locate
57 - open-file
58 - perldoc
59 - process
60 - programs
61 - screens
62 - searcher (ag/ack)
63 - ssh-hosts
64 - tmux
65 - widgets
66
67 (Note: git-files-legacy is an alternative for git-files.
68 git-files classifies modified files, git-files-legacy doesn't do it for
69 performance reason.)
70
71 Additional sources can be installed as third-party plugins. Here is a list of all
72 the ones we know about. Please let us know about any more you find or make!
73 Installation is easiest with a plugin manager such as
74 `zgen <https://github.com/tarjoilija/zgen>`_. Otherwise you can just source the
75 .zsh file that contains the source.
76
77 - calibre source: https://github.com/junkblocker/calibre-zaw-source
78 - MPD source: https://github.com/willghatch/zsh-zaw-mpd
79 - `pass <http://www.passwordstore.org>`_ source: https://gist.github.com/f440/9992963
80 - systemd source: https://github.com/termoshtt/zaw-systemd
81 - `todoman <https://github.com/hobarrera/todoman>`_ source: https://github.com/willghatch/zsh-zaw-todoman
82
83 shortcut widgets
84 ================
85
86 zaw automaticaly create shortcut widgets for each sources
87 that directly access to the source.
88
89 for example, execute ``bindkey '^R' zaw-history`` and
90 press ``^R`` to access history source.
91
92 you can get all available shortcut widgets' name using ``zaw-print-src``::
93
94 $ zaw-print-src
95 source name shortcut widget name
96 ----------------------------------------
97 ack zaw-ack
98 applications zaw-applications
99 bookmark zaw-bookmark
100 git-branches zaw-git-branches
101 git-recent-all-branches zaw-git-recent-all-branches
102 git-recent-branches zaw-git-recent-branches
103 git-files zaw-git-files
104 git-files-legacy zaw-git-files-legacy
105 git-status zaw-git-status
106 history zaw-history
107 open-file zaw-open-file
108 perldoc zaw-perldoc
109 process zaw-process
110 screens zaw-screens
111 ssh-hosts zaw-ssh-hosts
112 tmux zaw-tmux
113 fasd zaw-fasd
114 fasd-directories zaw-directories
115 fasd-files zaw-files
116
117
118 key binds and styles
119 ====================
120
121 zaw use ``filter-select`` to filter and select items.
122
123 you can use these key binds::
124
125 enter: accept-line (execute default action)
126 meta + enter: accept-search (execute alternative action)
127 Tab: select-action
128 ^G: send-break
129 ^H, backspace: backward-delete-char
130 ^F, right key: forward-char
131 ^B, left key: backward-char
132 ^A: beginning-of-line
133 ^E: end-of-line
134 ^W: backward-kill-word
135 ^K: kill-line
136 ^U: kill-whole-line
137 ^N, down key: down-line-or-history (select next item)
138 ^P, up key: up-line-or-history (select previous item)
139 ^V, page up key: forward-word (page down)
140 ^[V, page down key: backward-word (page up)
141 ^[<, home key: beginning-of-history (select first item)
142 ^[>, end key: end-of-history (select last item)
143
144 and these zstyles to customize styles::
145
146 ':filter-select:highlight' selected
147 ':filter-select:highlight' matched
148 ':filter-select:highlight' marked
149 ':filter-select:highlight' title
150 ':filter-select:highlight' error
151 ':filter-select' max-lines
152 ':filter-select' rotate-list
153 ':filter-select' case-insensitive
154 ':filter-select' extended-search
155 ':filter-select' hist-find-no-dups
156 ':filter-select' escape-descriptions
157
158 example:
159 zstyle ':filter-select:highlight' matched fg=yellow,standout
160 zstyle ':filter-select' max-lines 10 # use 10 lines for filter-select
161 zstyle ':filter-select' max-lines -10 # use $LINES - 10 for filter-select
162 zstyle ':filter-select' rotate-list yes # enable rotation for filter-select
163 zstyle ':filter-select' case-insensitive yes # enable case-insensitive search
164 zstyle ':filter-select' extended-search yes # see below
165 zstyle ':filter-select' hist-find-no-dups yes # ignore duplicates in history source
166 zstyle ':filter-select' escape-descriptions no # display literal newlines, not \n, etc
167
168 extended-search:
169 If this style set to be true value, the searching bahavior will be
170 extended as follows:
171
172 ^ Match the beginning of the line if the word begins with ^
173 $ Match the end of the line if the word ends with $
174 ! Match anything except the word following it if the word begins with !
175 so-called smartcase searching
176
177 If you want to search these metacharacters, please doubly escape them.
178
179 environment variable
180 ====================
181
182 ZAW_EDITOR editor command. If this variable is not set, use EDITOR value.
183 ZAW_EDITOR_JUMP_PARAM open editor command with line params.
184 %LINE% is replaced by line number.
185 %FILE% is replaced by file path.
186 default +%LINE% %FILE%
187
188
189 making sources
190 ==============
191
192 If you want to make another source, please do! Look at https://github.com/termoshtt/zaw-systemd
193 as an example of how to make a source repo. Note that it uses the <name>.plugin.zsh
194 convention that plugin managers like zgen and antigen expect for its main file.
195 The sources directory contains the files for the actual sources. All the sources
196 in this repository's ``sources`` directory are good references as well for what
197 the source files should look like. They tend to be quite simple.
198 If your source requires any additional configuration or dependencies, be sure to
199 list all of that in your project's README file.
200
201 Let us know when you make new plugins so we can add them to our list!
202
203 license
204 =======
205
206 BSD-3