You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Cz is a bash script that provides a common interface to interactive line selection tools.
5
+
Cz is a bash script that provides a common interface to interactive line
6
+
selection tools.
6
7
7
-
What is an "interactive line selection tool"? It's a class of programs that take as input a list of lines to be selected from then presents an interactive menu for the user to select one line.
8
+
What is an "interactive line selection tool"? It's a kind of program
9
+
that reads text input then presents an interactive menu for the user to
10
+
select one line.
8
11
9
-
Some run only in the terminal and others are graphical - cz runs an avalable tool appropriate for the situation.
12
+
Some line selection tools run only in the terminal and others are
13
+
graphical - cz uses a tool appropriate for the situation.
10
14
11
-
Cz also acts as a framework for pluggable line selection based applications.
15
+
Cz also acts as a framework for pluggable line selection based
16
+
applications. Included are over 250 plugins covering a variety of use
17
+
cases. For example:
12
18
13
-
Included are over 240 plugins for common use cases. Out of the box you can select from:
14
-
15
-
- files and directories
16
-
- system processes
17
-
- items from [bash's built-in completion](https://www.gnu.org/software/bash/manual/bash.html#Programmable-Completion-Builtins-1)
18
-
-[git](https://git-scm.com/) branches, commits, tags, etc.
Do you find yourself running commands just to copy some specific string into another command? Do you turn to a search engine for data that is available locally? With cz a short script can eliminate that repeated toil.
35
-
36
-
The core concept of cz is getting some known text into place as easily as possible. In a shell cz lets you select and insert commonly needed text right where it's needed. In a graphical environment cz can quickly select the text you need and get it onto your clipboard.
37
-
38
36
## Tools
39
37
40
-
Cz supports the following line selection tools:
38
+
The following line selection tools are
39
+
supported:
41
40
42
41
-[choose](https://github.com/chipsenkbeil/choose)
43
42
-[dmenu](https://tools.suckless.org/dmenu)
@@ -72,15 +71,15 @@ bash\`.
72
71
73
72
cz [OPTIONS] [PLUGIN...] [ARGS ...] [< LINES]
74
73
Select a line using your preferred interactive line selection tool.
75
-
74
+
76
75
OPTIONS
77
76
These options print some information and exit:
78
77
-h : help : Show this help text or help text for plugin.
79
78
-H : example : List example commands.
80
79
-k : tools : List supported line selection tools.
81
80
-l : plugins : List detected plugins.
82
81
-v : version : Show version string.
83
-
82
+
84
83
These options set the program mode. Select a line then... :
85
84
-p : print : Print the line. This is the default mode.
86
85
-q : quoted : Print fields from the line in shell quotes.
@@ -89,48 +88,48 @@ bash\`.
89
88
-t : template : Print a templated string.
90
89
-u : unquoted : Print fields from the line literally.
91
90
-o : : Only print input lines instead of selecting a line.
92
-
91
+
93
92
These options set a template:
94
93
-e TEMPLATE : Set the command template. This option implies mode '-r'.
95
94
-f FIELDS : Set the field template. This option implies mode '-q'.
96
-
95
+
97
96
These options control input and line splitting:
98
97
-c : Do not use cached input lines.
99
98
-d DELIMITER : Set the field splitting characters.
100
99
-g : Buffer stdin and pass it to command set with '-e'.
101
100
-0 : Read null terminated lines from input.
102
101
-i IN-FILE : Set file from which to read selections instead of stdin.
103
-
102
+
104
103
These options control which line selection utility is used:
105
104
-x : Use a graphical line selection tool.
106
105
-y : Use a terminal line selection tool.
107
106
-z TOOL : Use the given line selection tool.
108
-
107
+
109
108
TOOLS
110
109
The following interactive line selection tools are supported:
Plugins use cz for an application specific task. Each plugin defines input
116
115
lines and options like the delimiter and templates.
117
116
Run 'cz -l' to list plugins and 'cz -h PLUGIN' or 'cz help' for help text.
118
117
All commands starting with 'cz_' are considered plugins.
119
-
118
+
120
119
TEMPLATES
121
-
Substrings of TEMPLATE in the following formats are replaced with
120
+
Sub-strings of TEMPLATE in the following formats are replaced with
122
121
one or more fields from a selected line split by DELIMITER.
123
122
{X} - field X
124
123
{X:} - fields X through end of fields
125
124
{X:Y} - fields X through X + Y
126
125
{X,Y,Z} - fields X, Y, and Z
127
-
126
+
128
127
Append @C, @E, @P, or @Q to transform selected fields:
129
128
{X@C} - Insert argument directly. This is risky for command strings!
130
129
{X@E} - Replace backslash escape sequences in arguments with bash $'...' quotes.
131
130
{X@P} - Expand arguments for use in prompt strings.
132
131
{X@Q} - Quote arguments for use in command input. This is the default.
133
-
132
+
134
133
ENVIRONMENT
135
134
CZ_GUI : The preferred interface (1=graphical 0=terminal).
136
135
CZ_BINS : A list of line selection tools in order of preference.
@@ -140,97 +139,86 @@ bash\`.
140
139
141
140
## Configuration
142
141
143
-
To get the most out of cz users should consider binding shell and window manager keys.
142
+
To get the most out of cz users should consider binding shell and window
143
+
manager keys.
144
144
145
145
### Bash
146
146
147
-
Download this [example bash config](conf/cz.bashrc) then copy it into
147
+
Download this \[example bash config\](conf/cz.bashrc) then copy it into
148
148
your bashrc file.
149
149
150
-
The example config defines several key bindings that each *insert text into the shell's edit buffer* or run a relevant interactive program like $EDITOR.
151
-
152
-
- C-x x : select a plugin, run it, and insert fields from the selected
153
-
line
154
-
- C-x X : select a plugin, run it, and insert the selected line
155
-
- C-x z : select a plugin, run it, and insert templated command output
156
-
- C-x Z : select a plguin, run it, and insert templated command string
157
-
- C-x r : Select and insert a command from history
158
-
- C-x u : select and insert a unicode character
159
-
- C-x g : select an uncomitted file in current git repo and insert its
160
-
path
161
-
- C-x G : select a comitted file in current git repo and insert its
162
-
path
163
-
- C-x d : select a directory matching the word at cursor
164
-
- C-x D : select a directory under the directory at cursor
165
-
- C-x f : select a file matching the word at cursor
166
-
- C-x F : select a file under the directory at cursor
167
-
- C-x l : select a file in the locate database matching word at cursor
168
-
- C-x e : select a file containing the word at cursor
169
-
- C-x E : edit the line matching the pattern at cursor
170
-
171
-
Bash users should source cz to load included function 'rleval'.
172
-
173
-
rleval [OPTIONS] COMMAND [ARGS ...]
174
-
Evaluate command then...
175
-
-i : insert its output into the readline buffer at cursor point.
176
-
-w : replace the word at cursor point with its output.
177
-
-r : run the command attached to the terminal.
178
-
179
-
The command string is templated using the current readline tokens.
180
-
The word at cursor point is '{0}'. The first token in the command is '{1}' and so on.
181
-
This function is intended to be used with the bash builtin 'bind -x'.
182
-
183
-
EXAMPLES
184
-
Insert the first token from the current readline buffer:
185
-
$ bind -x '"\C-x0":rleval -i echo {1}'
186
-
187
-
Insert fortunes on demand:
188
-
$ bind -x '"\C-xf":rleval -i fortune"'
189
-
190
-
Replace the current word with a generated password:
191
-
$ bind -x '"\C-xp":rleval -w pwgen 20 1'
192
-
193
-
Replace the current word with itself reversed:
194
-
$ bind -x '"\C-xt":rleval -w "rev <<< {0}"'
195
-
196
-
Encode and decode base64 strings at cursor point:
197
-
$ bind -x '"\C-xb":rleval -w "base64 <<< {0}"'
198
-
$ bind -x '"\C-xB":rleval -w "base64 -d <<< {0}"'
199
-
200
-
Open the man page for the topic at cursor point:
201
-
$ bind -x '"\C-xh":rleval -r man {0}'
150
+
The example config defines key bindings that run cz to provide
151
+
interactive functionality.
152
+
153
+
Some of the key bindings use the included function \`reval\` to do one
154
+
of the following:
155
+
156
+
- Insert output from cz into the bash command buffer at cursor point.
157
+
- Replace the word at cursor point in the bash command buffer with
158
+
output from cz.
159
+
- Run cz to launch an interactive program (like $EDITOR) using some
160
+
part of the selection.
161
+
162
+
The example key bindings are as follows:
163
+
164
+
- C-x x : Select a cz plugin, run it in quote mode, and insert one or
165
+
more fields from the selection.
166
+
- C-x X : Select a cz plugin, run it print mode, and insert the
167
+
selection.
168
+
- C-x z : Select a cz plugin, run it in run mode, and insert the
169
+
output of the command.
170
+
- C-x Z : Select a cz plguin, run it in simulate mode and insert the
171
+
command templated with the selection.
172
+
- C-x r : Select a command from bash history and insert it.
173
+
- C-x u : Select a unicode character and insert it.
174
+
- C-x g : Select an uncomitted file in current git repository and
175
+
insert its path.
176
+
- C-x G : Select a comitted file in current git repository and insert
177
+
its path.
178
+
- C-x d : Using the current word as a directory, replace it with a
179
+
selected descendant directory.
180
+
- C-x D : Using the current word as a pattern, replace it with a
181
+
selected matching descendant directory under $PWD.
182
+
- C-x f : Using the current word as a directory, replace it with a
183
+
selected descendant file.
184
+
- C-x F : Using the current word as a pattern, replace it with a
185
+
selected matching descendant file under $PWD.
186
+
- C-x l : Using the current word as a pattern, replace it with a
187
+
selected matching file from the locate database.
188
+
- C-x e : Using the current word as a pattern, replace it with the
189
+
path of a file matching it under $PWD.
190
+
- C-x E : Using the current word as a pattern, run $EDITOR to open
191
+
selected file matching it under $PWD.
202
192
203
193
### Zsh
204
194
205
-
Download this [example zsh config](conf/cz.zshrc) then copy it into
206
-
your zshrc file.
195
+
Download the example zsh config then copy it into your zshrc file.
207
196
208
197
The example config defines the same key bindings described in the bash
209
198
section above.
210
199
211
200
### i3 Window Manager
212
201
213
-
Download this [example i3 config](conf/cz-i3.conf) then copy it into
214
-
your i3 config.
202
+
Download the example i3 config then copy it into your i3 config.
215
203
216
204
The example config defines the following key bindings:
217
205
218
-
- Mod-x : select a plugin, run it, and put fields from selected line
219
-
into a clipboard
220
-
- Mod-X : select a plugin, run it, and put selected line into a
221
-
clipboard
222
-
- Mod-z : select a plugin, run it, and put command output into a
223
-
clipboard
224
-
- Mod-Z : select a plguin, run it, and put command string into a
206
+
- Mod-x : Select a cz plugin, run it, and put fields from selected
207
+
line into a clipboard
208
+
- Mod-X : Select a cz plugin, run it, and put selected line into a
225
209
clipboard
226
-
- Mod-c : select a command and run it
227
-
- Mod-C : select a clipboard and pipe its contents through the
210
+
- Mod-z : Select a cz plugin, run it in , and put command output into
211
+
a clipboard
212
+
- Mod-Z : Select a cz plguin, run it in simulate mode, and put the
213
+
output into a clipboard
214
+
- Mod-c : Select a command and run it
215
+
- Mod-C : Select a clipboard and pipe its contents through the
228
216
selected command
229
-
- Mod-o : select a clipboard then select from URLs extracted from its
217
+
- Mod-o : Select a clipboard then select a URL extracted from its
230
218
contents to open in a browser
231
-
- Mod-Shift-Space : select an i3 a tag and jump to the selected window
232
-
- Mod-Tab : select an i3 window and jump to it
233
-
- Mod-Shift-Tab : select an i3 workspace and switch to it
219
+
- Mod-Shift-Space : Select an i3 a tag and jump to the selected window
220
+
- Mod-Tab : Select an i3 window and jump to it
221
+
- Mod-Shift-Tab : Select an i3 workspace and switch to it
0 commit comments