Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CDARGS(1)		    General Commands Manual		     CDARGS(1)

       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 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 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 de-
	      scription	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	prese-

	      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 be-
	      havior by	using the "--noresolve"	option.	This  option  is  used
	      when  you	think you give a Needle	which matches descriptions ex-
	      actly but	you don't want it to be	resolved if it does. This  op-
	      tion 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 en-

	      Finally, if the filtered list (but not the bookmarks file)  con-
	      tains  only  one entry it	is selected and	the program exits suc-
	      cessfully, 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	 posi-
	      tion 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  wel-

       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

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

       $HOME/.cdargs 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 (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 op-
       tion) 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-
       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.,
       675 Mass	Ave, Cambridge,	MA 02139, USA.

				  March	2002			     CDARGS(1)


Want to link to this manual page? Use this URL:

home | help