1CDARGS(1)                   General Commands Manual                  CDARGS(1)
2
3
4

NAME

6       cdargs - bookmarks and browser for cd shell built-in
7

SYNOPSIS

9       cdargs [OPTIONS]
10       function cv () {
11           cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" ;
12       }
13       cv [Needle]
14

DESCRIPTION

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
19       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
23       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
29       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
34       For sh-like shells:
35       function cv () {
36           cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" ;
37       }
38
39       For csh-like shells:
40       alias cv 'cdargs \!* && cd `cat $HOME/.cdargsresult`'
41
42       Now you only have to put the cdargs binary somewhere into your path.
43
44       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
49       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
55

COMMAND-LINE OPTIONS

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
60       -h or --help
61              display usage information and exit.
62
63       -v or --version
64              output version information and exit.
65
66       -a or --add=[:desc:]path
67              add  path  to  the  bookmarks  list  using  the optional desc as
68              description string.
69
70       -f or --file=FILE
71              uses the given FILE as bookmarks file
72
73       -u or --user=USER
74              read the default bookmarks file of USER. Won't modify that file.
75
76       -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
80       -b or --browse
81              start cdargs in BROWSE mode in the current directory.
82
83       -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
88       -c or --cwd
89              Make  the current working directory the current entry on startup
90              if it appears on the list.
91
92       --nowrap
93              Don't wrap the cursor around when hitting the end of the list.
94
95       Needle The Needle performs some magic which I hope improves  the  usage
96              of cdargs.
97
98              The  Needle  is  examined  in  the following order and the first
99              thing that fits is taken.
100
101              If Needle is a one-digit integer the appropriate entry is prese‐
102              lected.
103
104              Otherwise  if  Needle  is  a  string  each  entry of the list is
105              checked whether it contains Needle.
106
107              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
111              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
115              If it doesn't match a line, that line won't be displayed.
116
117              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
126              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
130              I can only hope that you understand this nested if babble...
131
132              Please note, that the existence of a Needle disables the  saving
133              of the list at the end of the program.
134
135

COMMANDS

137       When  you are in cdargs you have two modes and several commands at your
138       hands.
139
140       The two modes are LIST (when  your  bookmark  list  is  displayed)  and
141       BROWSE (when you navigate through the file-system).
142
143       The  navigation keys are mostly available in Emacs and vi style for all
144       maniacs out there.
145
146       Common Keys
147
148       <UP>/<DOWN> or k/j or C-n/C-p
149              move selection up/down and scroll.
150
151       <ENTER>
152              select current entry.
153
154       <TAB>  toggle modes: LIST or BROWSE.
155
156       <HOME>/<END> or C-a/C-e
157              goto first/last entry in list.
158
159       c      add current directory to list.
160
161       C      add current directory to list but ask the user for a description
162
163       <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
167       e, v   edit the list in $EDITOR.
168
169       H, ?   show the help-screen.
170
171       ~, /   browse home/root directory.
172
173       q      quit - saving the list.
174
175       C-c, C-g, C-[
176              abort - don't save the list.
177
178       Keys in BROWSE mode
179
180       <LEFT>, h, C-b
181              descent into current directory.
182
183       <RIGHT>, l, C-f
184              up one directory.
185
186       [num]  make [num] the current highlighted entry
187
188       a      add current entry to list.
189
190       A      add  current  entry  to list but ask the user for a description,
191              just like with 'c' and 'C'.
192
193       .      toggle display of hidden files.
194
195       Keys in LIST mode
196
197       [num]  select and resolve entry [num] if displayed.
198
199       <LEFT>, h, C-b
200              descent into the current entry.
201
202       <RIGHT>, l, C-f
203              up one directory from current dir.
204
205       d or C-d
206              delete current entry from list.
207
208       s or t swap (transpose) two entries of the list.
209
210       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
214
215

SHELL FUNCTIONS

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
221       function cv () {
222           cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`"
223                       && pwd;
224       }
225
226       Or you can remove the file in which cdargs reports it's result:
227
228       function cv () {
229           cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`"
230                       && rm -f "$HOME/.cdargsresult";
231       }
232
233       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
238       cv [TAB]
239
240       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
245

DISPLAY

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
250       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
253       B      for BROWSE
254
255       L      for LIST
256
257       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
267       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
271
272

FILES

274       $HOME/.cdargs personal bookmarks file.
275
276       $HOME/.cdargsresult
277              temporary file for passing results to shell.
278
279       contrib/cdargs-bash.sh
280              example collection of bash functions.
281
282       contrib/cdargs-tcsh.csh
283              example collection of tcsh functions.
284
285       contrib/cdargs.el
286              (X)Emacs front-end to personal bookmarks file
287
288

REPORTING BUGS

290       Report bugs to <mail@skamphausen.de>.
291

AUTHOR

293       cdargs was written by Stefan Kamphausen with add-ons by Claus Brunzema.
294       Many user-interface improvements came from Dan Allen.
295

SEE ALSO

297       The current version of cdargs is located at
298
299              http://www.skamphausen.de/software/cdargs
300
301       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
307       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
312       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
317       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
321
322
323                                  March 2002                         CDARGS(1)
Impressum