Ubuntu Manpage: cdargs - bookmarks and browser for cd shell built-in

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.

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)