Provided by: cdargs_1.35-10_amd64 bug

NAME

       cdargs - bookmarks and browser for cd shell built-in

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 function. 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 purposes. You might want
       to add a pwd call to echo your current directories 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.

       -h or --help
              display usage information and exit.

       -v or --version
              output version information and exit.

       -a or --add=[:desc:]path
              add path to the bookmarks list using the optional desc as description string.

       -f or --file=FILE
              uses the given FILE as bookmarks file

       -u or --user=USER
              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 preselected.

              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 (otherwise the deletion of
              entries until only one entry is left would lead to resolving) or when the bookmarks
              file contains only one entry.

              Finally,  if the filtered list (but not the bookmarks file) contains only one entry
              it is selected and the program exits successfully, unless you chose --noresolve.

              I can only hope that you understand this nested if babble...

              Please note, that the existence of a Needle disables the saving of the list at  the
              end of the program.

COMMANDS

       When you are in cdargs you have two modes and several commands at your hands.

       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.

       A      add  current  entry  to list but ask the user for a description, just like with 'c'
              and 'C'.

       .      toggle display of hidden files.

       Keys in LIST mode

       [num]  select and resolve entry [num] if displayed.

       <LEFT>, h, C-b
              descent into the current entry.

       <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  position  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 welcome.

DISPLAY

       The cdargs window has one line at the bottom for the display of  messages  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 current directory and a
       one letter code for the current operation mode:

       B      for BROWSE

       L      for LIST

       The largest part of the display is used to show you either the list of your  bookmarks  or
       the  contents  of  the  current  directory. On the left side you'll probably find a number
       which you can use for a slightly quicker jumping compared to using  the  cursor  movement.
       These  numbers  can  be  moved  as described above. Next comes the short description of an
       entry in brackets. This is convient when you have quite long paths in your  bookmarks  and
       most  of  them  start  with  the same base (e.g.  /home/user). Finally there is the actual
       absolute path you'll be  warping  to  when  finishing.  Obviously  the  current  entry  is
       highlighted.

       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

       /usr/bin/cdargs the cdargs executable.

       $HOME/.cdargs
              personal bookmarks file.

       $HOME/.cdargsresult
              temporary file for passing results to shell.

       /usr/share/doc/cdargs/examples/cdargs-bash.sh
              example collection of bash functions.

       /usr/share/doc/cdargs/examples/cdargs-tcsh.csh
              example collection of tcsh functions.

       /usr/share/emacs/site-lisp/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 © 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 MERCHANTABILITY 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, see <http://www.gnu.org/licenses/>.

                                            March 2002                                  CDARGS(1)