SYNOPSIS
cdargs [OPTIONS]
function cv () {
cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" ;
}
cv [Needle]
DESCRIPTION
With cdargs you can jump to various places throughout the file-system
that are defined using a plain text, line oriented bookmarks file.
You can create bookmarks by editing your bookmarks file "$HOME/.cdargs"
using your favorite editor, by using the "--add" option to cdargs or by
using the built-in mechanism that will be described later.
While you are in cdargs you can use various commands to navigate
through your list of bookmarks and through the file-system. These are
described below in the section "COMMANDS". The most commonly used and
most obvious commands are the up/down keys for navigation, "ENTER" for
selection of a path and "q" for quit.
To be able to actually use this program together with the shell built-
in "cd" command you must use a little trick by defining a shell func-
tion. Of course the syntax for this is different between the csh-like
shells (like tcsh) and the sh-like shells (like bash).
For sh-like shells:
function cv () {
cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" ;
}
For csh-like shells:
alias cv 'cdargs \!* && cd `cat $HOME/.cdargsresult`'
Now you only have to put the cdargs binary somewhere into your path.
Of course you can create functions and/or aliases for different pur-
poses. You might want to add a pwd call to echo your current directo-
ries or put --nowrap in your functions to enable a different scrolling
behavior. See section SHELL FUNCTIONS below.
Since version 1.19 cdargs brings a collection of bash functions (and
since 1.20 tcsh aliases, too) with it. You only have to source this in
your ~/.profile or ~/.bashrc (or ~/.tcsh) and you get nice kinds of
magic prepared (completion...). Please read the cdargs-bash.sh or
cdargs-tcsh.csh respectively for the documentation of these functions.
COMMAND-LINE OPTIONS
You can call cdargs with a few options, but otherwise you probably
won't call it directly but via the function you defined.
read the default bookmarks file of USER. Won't modify that file.
-o or --output=FILE
use FILE as the result-file (who knows what The World might make
of this feature that I can't imagine...)
-b or --browse
start cdargs in BROWSE mode in the current directory.
-r or --noresolve
Don't exit with a result when the Needle matches a description
exactly (which is some every-day-magic) but show a list (even if
it contains just one entry).
-c or --cwd
Make the current working directory the current entry on startup
if it appears on the list.
--nowrap
Don't wrap the cursor around when hitting the end of the list.
Needle The Needle performs some magic which I hope improves the usage
of cdargs.
The Needle is examined in the following order and the first
thing that fits is taken.
If Needle is a one-digit integer the appropriate entry is prese-
lected.
Otherwise if Needle is a string each entry of the list is
checked whether it contains Needle.
Then Needle has two functions:
If it just matches a substring of either path or description
that option is placed in the list.
If it exactly matches a description string this is the result
(that means cdargs closes the curses window, exits and the
changing of directories takes place).
If it doesn't match a line, that line won't be displayed.
And to make things even more complicated you can affect this
behavior by using the "--noresolve" option. This option is used
when you think you give a Needle which matches descriptions
exactly but you don't want it to be resolved if it does. This
option is internally turned on when you delete an entry (other-
wise the deletion of entries until only one entry is left would
lead to resolving) or when the bookmarks file contains only one
entry.
The two modes are LIST (when your bookmark list is displayed) and
BROWSE (when you navigate through the file-system).
The navigation keys are mostly available in Emacs and vi style for all
maniacs out there.
Common Keys
<UP>/<DOWN> or k/j or C-n/C-p
move selection up/down and scroll.
<ENTER>
select current entry.
<TAB> toggle modes: LIST or BROWSE.
<HOME>/<END> or C-a/C-e
goto first/last entry in list.
c add current directory to list.
C add current directory to list but ask the user for a description
<PgUp>/<PgDown> or C-v
Scroll the list in 10-line-steps. This will never wraparound
and does not honor the nowrap-option
e, v edit the list in $EDITOR.
H, ? show the help-screen.
~, / browse home/root directory.
q quit - saving the list.
C-c, C-g, C-[
abort - don't save the list.
Keys in BROWSE mode
<LEFT>, h, C-b
descent into current directory.
<RIGHT>, l, C-f
up one directory.
[num] make [num] the current highlighted entry
a add current entry to list.
<RIGHT>, l, C-f
up one directory from current dir.
d or C-d
delete current entry from list.
s or t swap (transpose) two entries of the list.
M or m move an entry up or down in the list and set the current posi-
tion afterwards so that repeated keystrokes keep moving the same
entry up and down.
SHELL FUNCTIONS
In addition to the shell function mentioned above you might wish to add
other commands to your function. One example is to echo the directory
you changed to:
function cv () {
cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`"
&& pwd;
}
Or you can remove the file in which cdargs reports it's result:
function cv () {
cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`"
&& rm -f "$HOME/.cdargsresult";
}
Since version 1.19 cdargs comes with a file of preset functions for
bash: see cdargs-bash.sh in the distribution. From now on you only have
to source that file if you are using a sh-like shell. Then you can use
the shell completion to switch directories even faster by typing
cv [TAB]
Since version 1.20 cdargs comes with a file of rudimentary aliases (and
completion) for the tcsh.
Any volunteers for porting all the bash functionality to tcsh are wel-
come.
DISPLAY
The cdargs window has one line at the bottom for the display of mes-
sages like when you added to your list or when you hit an unknown key.
The second line from the bottom is a status line which shows the cur-
rent directory and a one letter code for the current operation mode:
B for BROWSE
If the path is preced by a "!" it points to an invalid directory. A
bookmark pointing to the current working directory is displayed in bold
font (if the terminal emulation understands that attribute).
FILES
$HOME/.cdargs personal bookmarks file.
$HOME/.cdargsresult
temporary file for passing results to shell.
contrib/cdargs-bash.sh
example collection of bash functions.
contrib/cdargs-tcsh.csh
example collection of tcsh functions.
contrib/cdargs.el
(X)Emacs front-end to personal bookmarks file
REPORTING BUGS
Report bugs to <mail@skamphausen.de>.
AUTHOR
cdargs was written by Stefan Kamphausen with add-ons by Claus Brunzema.
Many user-interface improvements came from Dan Allen.
SEE ALSO
The current version of cdargs is located at
http://www.skamphausen.de/software/cdargs
You might want to visit that site. Other than that pressing the 'H' key
in cdargs fires up a help screen.
COPYRIGHT
Copyright (C) 2001-2003 Stefan Kamphausen
cdargs 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 2 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 MER-
CHANTABILITY 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, write to the Free Software Foundation, Inc.,
Man(1) output converted with
man2html