Man Linux: Main Page and Category List


       cdargs - bookmarks and browser for cd shell built-in


       cdargs [OPTIONS]
       function cv () {
           cdargs "$1" && cd "cat "$HOME/.cdargsresult"" ;
       cv [Needle]


       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 or
       cdargs-tcsh.csh respectively for the documentation of these  functions.


       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.

              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

              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.


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

       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.

              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.


       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 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


       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

       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).


       /usr/bin/cdargs the cdargs executable.

              personal bookmarks file.

              temporary file for passing results to shell.

              example collection of bash functions.

              example collection of tcsh functions.

              (X)Emacs front-end to personal bookmarks file


       Report bugs to <>.


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


       The current version of cdargs is located at


       You might want to visit that site. Other than that pressing the ’H’ key
       in cdargs fires up a help screen.


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

                                  March 2002