1CDARGS(1) General Commands Manual CDARGS(1)
2
6 cdargs - bookmarks and browser for cd shell built-in
7
9 cdargs [OPTIONS]
10 function cv () {
11 cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" ;
12 }
13 cv [Needle]
14
16 With cdargs you can jump to various places throughout the file-system
17 that are defined using a plain text, line oriented bookmarks file.
18 You can create bookmarks by editing your bookmarks file "$HOME/.cdargs"
20 using your favorite editor, by using the "--add" option to cdargs or by
21 using the built-in mechanism that will be described later.
22 While you are in cdargs you can use various commands to navigate
24 through your list of bookmarks and through the file-system. These are
25 described below in the section "COMMANDS". The most commonly used and
26 most obvious commands are the up/down keys for navigation, "ENTER" for
27 selection of a path and "q" for quit.
28 To be able to actually use this program together with the shell built-
30 in "cd" command you must use a little trick by defining a shell func‐
31 tion. Of course the syntax for this is different between the csh-like
32 shells (like tcsh) and the sh-like shells (like bash).
33 For sh-like shells:
35 function cv () {
36 cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" ;
37 }
38 For csh-like shells:
40 alias cv 'cdargs \!* && cd `cat $HOME/.cdargsresult`'
41 Now you only have to put the cdargs binary somewhere into your path.
43 Of course you can create functions and/or aliases for different pur‐
45 poses. You might want to add a pwd call to echo your current directo‐
46 ries or put --nowrap in your functions to enable a different scrolling
47 behavior. See section SHELL FUNCTIONS below.
48 Since version 1.19 cdargs brings a collection of bash functions (and
50 since 1.20 tcsh aliases, too) with it. You only have to source this in
51 your ~/.profile or ~/.bashrc (or ~/.tcsh) and you get nice kinds of
52 magic prepared (completion...). Please read the cdargs-bash.sh or
53 cdargs-tcsh.csh respectively for the documentation of these functions.
54
57 You can call cdargs with a few options, but otherwise you probably
58 won't call it directly but via the function you defined.
59 -h or --help
61 display usage information and exit.
62 -v or --version
64 output version information and exit.
65 -a or --add=[:desc:]path
67 add path to the bookmarks list using the optional desc as
68 description string.
69 -f or --file=FILE
71 uses the given FILE as bookmarks file
72 -u or --user=USER
74 read the default bookmarks file of USER. Won't modify that file.
75 -o or --output=FILE
77 use FILE as the result-file (who knows what The World might make
78 of this feature that I can't imagine...)
79 -b or --browse
81 start cdargs in BROWSE mode in the current directory.
82 -r or --noresolve
84 Don't exit with a result when the Needle matches a description
85 exactly (which is some every-day-magic) but show a list (even if
86 it contains just one entry).
87 -c or --cwd
89 Make the current working directory the current entry on startup
90 if it appears on the list.
91 --nowrap
93 Don't wrap the cursor around when hitting the end of the list.
94 Needle The Needle performs some magic which I hope improves the usage
96 of cdargs.
97 The Needle is examined in the following order and the first
99 thing that fits is taken.
100 If Needle is a one-digit integer the appropriate entry is prese‐
102 lected.
103 Otherwise if Needle is a string each entry of the list is
105 checked whether it contains Needle.
106 Then Needle has two functions:
108 If it just matches a substring of either path or description
109 that option is placed in the list.
110 If it exactly matches a description string this is the result
112 (that means cdargs closes the curses window, exits and the
113 changing of directories takes place).
114 If it doesn't match a line, that line won't be displayed.
116 And to make things even more complicated you can affect this
118 behavior by using the "--noresolve" option. This option is used
119 when you think you give a Needle which matches descriptions
120 exactly but you don't want it to be resolved if it does. This
121 option is internally turned on when you delete an entry (other‐
122 wise the deletion of entries until only one entry is left would
123 lead to resolving) or when the bookmarks file contains only one
124 entry.
125 Finally, if the filtered list (but not the bookmarks file) con‐
127 tains only one entry it is selected and the program exits suc‐
128 cessfully, unless you chose --noresolve.
129 I can only hope that you understand this nested if babble...
131 Please note, that the existence of a Needle disables the saving
133 of the list at the end of the program.
134
137 When you are in cdargs you have two modes and several commands at your
138 hands.
139 The two modes are LIST (when your bookmark list is displayed) and
141 BROWSE (when you navigate through the file-system).
142 The navigation keys are mostly available in Emacs and vi style for all
144 maniacs out there.
145 Common Keys
147 <UP>/<DOWN> or k/j or C-n/C-p
149 move selection up/down and scroll.
150 <ENTER>
152 select current entry.
153 <TAB> toggle modes: LIST or BROWSE.
155 <HOME>/<END> or C-a/C-e
157 goto first/last entry in list.
158 c add current directory to list.
160 C add current directory to list but ask the user for a description
162 <PgUp>/<PgDown> or C-v
164 Scroll the list in 10-line-steps. This will never wraparound
165 and does not honor the nowrap-option
166 e, v edit the list in $EDITOR.
168 H, ? show the help-screen.
170 ~, / browse home/root directory.
172 q quit - saving the list.
174 C-c, C-g, C-[
176 abort - don't save the list.
177 Keys in BROWSE mode
179 <LEFT>, h, C-b
181 descent into current directory.
182 <RIGHT>, l, C-f
184 up one directory.
185 [num] make [num] the current highlighted entry
187 a add current entry to list.
189 A add current entry to list but ask the user for a description,
191 just like with 'c' and 'C'.
192 . toggle display of hidden files.
194 Keys in LIST mode
196 [num] select and resolve entry [num] if displayed.
198 <LEFT>, h, C-b
200 descent into the current entry.
201 <RIGHT>, l, C-f
203 up one directory from current dir.
204 d or C-d
206 delete current entry from list.
207 s or t swap (transpose) two entries of the list.
209 M or m move an entry up or down in the list and set the current posi‐
211 tion afterwards so that repeated keystrokes keep moving the same
212 entry up and down.
213
217 In addition to the shell function mentioned above you might wish to add
218 other commands to your function. One example is to echo the directory
219 you changed to:
220 function cv () {
222 cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`"
223 && pwd;
224 }
225 Or you can remove the file in which cdargs reports it's result:
227 function cv () {
229 cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`"
230 && rm -f "$HOME/.cdargsresult";
231 }
232 Since version 1.19 cdargs comes with a file of preset functions for
234 bash: see cdargs-bash.sh in the distribution. From now on you only have
235 to source that file if you are using a sh-like shell. Then you can use
236 the shell completion to switch directories even faster by typing
237 cv [TAB]
239 Since version 1.20 cdargs comes with a file of rudimentary aliases (and
241 completion) for the tcsh.
242 Any volunteers for porting all the bash functionality to tcsh are wel‐
243 come.
244
247 The cdargs window has one line at the bottom for the display of mes‐
248 sages like when you added to your list or when you hit an unknown key.
249 The second line from the bottom is a status line which shows the cur‐
251 rent directory and a one letter code for the current operation mode:
252 B for BROWSE
254 L for LIST
256 The largest part of the display is used to show you either the list of
258 your bookmarks or the contents of the current directory. On the left
259 side you'll probably find a number which you can use for a slightly
260 quicker jumping compared to using the cursor movement. These numbers
261 can be moved as described above. Next comes the short description of an
262 entry in brackets. This is convient when you have quite long paths in
263 your bookmarks and most of them start with the same base (e.g.
264 /home/user). Finally there is the actual absolute path you'll be warp‐
265 ing to when finishing. Obviously the current entry is highlighted.
266 If the path is preced by a "!" it points to an invalid directory. A
268 bookmark pointing to the current working directory is displayed in bold
269 font (if the terminal emulation understands that attribute).
270
274 $HOME/.cdargs personal bookmarks file.
275 $HOME/.cdargsresult
277 temporary file for passing results to shell.
278 contrib/cdargs-bash.sh
280 example collection of bash functions.
281 contrib/cdargs-tcsh.csh
283 example collection of tcsh functions.
284 contrib/cdargs.el
286 (X)Emacs front-end to personal bookmarks file
287
290 Report bugs to <mail@skamphausen.de>.
291
293 cdargs was written by Stefan Kamphausen with add-ons by Claus Brunzema.
294 Many user-interface improvements came from Dan Allen.
295
297 The current version of cdargs is located at
298 http://www.skamphausen.de/software/cdargs
300 You might want to visit that site. Other than that pressing the 'H' key
302 in cdargs fires up a help screen.
303
305 Copyright © 2001-2003 Stefan Kamphausen
306 cdargs is free software; you can redistribute it and/or modify it under
308 the terms of the GNU General Public License as published by the Free
309 Software Foundation; either version 2 of the License, or (at your
310 option) any later version.
311 This program is distributed in the hope that it will be useful, but
313 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
314 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
315 Public License for more details.
316 You should have received a copy of the GNU General Public License along
318 with this program; if not, write to the Free Software Foundation, Inc.,
319 675 Mass Ave, Cambridge, MA 02139, USA.
320 March 2002 CDARGS(1)