apparix man page on DragonFly

Printed from http://www.polarhome.com/service/man/?qf=apparix&af=0&tf=2&of=DragonFly

apparix(1)			USER COMMANDS			    apparix(1)

  NAME
      apparix - augmenting cd with bookmarks

  SYNOPSIS
      Apparix  allows you to bookmark directories and later jump to them using
      the mark.	 By default apparix acts as a replacement for cd  and  can  be
      used  in the same manner, including the special behaviour for cd without
      argument and cd -.  It is possible to directly jump to subdirectories of
      a	 bookmarked  directory.	  The contributed bash completion code facili‐
      tates completion both on bookmarks and directories, but can be  adjusted
      to accomodate other preferences.

      This  manual  page  suffers  from an excess in verbosity due to the many
      examples, explanations of the bells and whistles, and  comparisons  with
      other  approaches	 to  bookmarking.  The fundamental idea is simply that
      typing a string of your own choosing takes you to the directory  associ‐
      ated  with it.  Apparix does little more than maintaining a list of keys
      and values.  It obtains directory names and  listings,  associates  path
      names (values) with bookmarks (keys), and has some facilities for manip‐
      ulating keys and values. The functions involving apparix	(bm,  to,  and
      portal)  provide	the user interface.  Other functions, als (apparix ls)
      and  ae  (apparix	 edit)	are  discussed	on  the	 main	apparix	  page
      http://micans.org/apparix.

  GETTING STARTED
      Install	apparix.   This	 should	 be  as	 easy  as  ./configure	--pre‐
      fix=$HOME/local && make &&  make	install,  or  perhaps  a  pre-packaged
      apparix  is  available for your system.  Then get hold of the to, bm and
      portal shell handles. These are either aliases or functions depending on
      your  shell. Currently csh-style shells and bash are supported.  Get the
      ones you need preferably from  http://micans.org/apparix/#shell.	For  a
      more  limited  set  of commands either visit the FILES section, or issue
      apparix --shell-examples. Activate them by  simply  pasting  them	 in  a
      shell or adding them to the appropriate resource file, e.g. $HOME/.cshrc
      or $HOME/.bashrc (do not forget to source the resource file).  The  han‐
      dles  to,	 bm  and  portal can of course be changed to any name desired.
      With these preliminaries, the following is a  mock-up  shell  navigation
      session.

	 > pwd
	 /home/eez/cvs/xyz/tfa/faq/zut/bar/foo
	 > ls
	 src/ doc/ CVS/ bin/
	 > bm xkr	# bookmark as xkr (funny name though)
	 > bm		# bookmark as foo (trailing component is default)
      (later)
	 > to xkr	# cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo
      (alternatively)
	 > to xkr src	# cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo/src
      (alternatively)
	 > to foo	# cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo

      (later)
	 > ls
	 aap pyu/ qua tim/ zut/
	 > pwd
	 /home/eez/another/branch/deep/down/under
	 > portal	# bookmark as portal, imports tim zut pyu bookmarks
	 added flock of 3 in portal /home/eez/another/branch/deep/down/under

      (later)
	 > to zut	# cd to /home/eez/another/branch/deep/down/under/zut

      (later)
	 > apparix   # show all bookmarks
	 --- portals
	 e		/home/eez/another/branch/deep/down/under
	 --- expansions
	 j pyu		/home/eez/another/branch/deep/down/under/pyu
	 j tim		/home/eez/another/branch/deep/down/under/tim
	 j zut		/home/eez/another/branch/deep/down/under/zut
	 --- bookmarks
	 j xkr		/home/eez/cvs/xyz/tfa/faq/zut/bar/foo
	 j foo		/home/eez/cvs/xyz/tfa/faq/zut/bar/foo

      In  the  last  example apparix simply shows all its bookmarks. The first
      batch shows portals. The second batch shows secondary bookmarks expanded
      from portals. The third batch shows all regular bookmarks.

      In  the  default definitions of to it falls back to regular cd behaviour
      in case a mark is not found. This is  done  by  instructing  apparix  to
      check whether the mark exists as the name of a directory. It is possible
      to do this either before or after bookmark lookup, or  not  at  all.  By
      default  the  bash completion code takes into account both bookmarks and
      directories.

      Apparix also allows subdirectory specification of bookmarked  locations.
      If  this	is combined with the bash completion code it yields a powerful
      way of navigating container directories, i.e. directories that contain a
      large  number of subdirectories. Refer to the subdirectory specification
      section.

      Further options
      [--add-mark (add jump bookmark)] [--add-portal  (add  portal  bookmark)]
      [-sm <mark> (squash repeated marks)] [-sd <mark> (squash repeated desti‐
      nations)] [-lm <mark> (list bookmarks with this mark)] [-ld <mark> (list
      destinations  with mark indirection)] [-favour <list> (duplicate resolu‐
      tion policy)] [-pick <num> (immediate duplicate resolution)] [-purge pat
      (delete  bookmarks)] [-purge-mark (pat)] [-d (dump resource file to STD‐
      OUT)] [-l (list available jumps)] [-u <num>  (remove  last  <num>	 addi‐
      tions)]  [--rehash (re-expand portal bookmarks)] [--bu (create backup of
      resource file)] [-bu <fname> (create backup  in  <fname>)]  [--cwd  (use
      getcwd(3), not pwd(1))] [--shell-examples (output example macros)]

  DESCRIPTION
      Apparix  combines	 the  properties  of the cdargs utility and the CDPATH
      shell mechanism for fast navigation through  the	file  system.  It  can
      additionally  act as the regular cd command. It is especially useful for
      visiting and documenting both often- and rarely-used locations.  Apparix
      enables  you to attach marks to locations and jump to those locations by
      loading the mark. Marking, unmarking and jumping are  simple  operations
      that  are performed in the shell. All actions take effect immediately in
      all shells running. By setting up convenient  aliases  for  marking  and
      jumping the file system can be navigated in a fast and intuitive manner.
      The FILES section lists aliases for csh-type shells  and	functions  for
      bash, including the setup to equip the to function with argument comple‐
      tion in bash.

      This section contains some examples of the most common uses of  apparix.
      OPTIONS  contains	 a  list  of additional options available for listing,
      pruning, and squashing bookmarks.

      NOTES features a brief discussion of  the	 advantages  of	 apparix  over
      other  approaches	 such as setting up aliases for often visited directo‐
      ries, using  symlinks,  CDPATH,  or  a  combination  of  these.  HISTORY
      explains the difference between cdargs and apparix.  The sections dupli‐
      cate resolution, subdirectory specification, tab completion, copying and
      moving files, listing bookmarks, and replacing cd further below are also
      recommended reading.

      Apparix works in a manner similar to cdargs. One usually invokes apparix
      by  using pre-defined aliases. Here they will be called bm for bookmark,
      portal for a CDPATH-style bookmark and to for initiating	an  apparition
      (aka  jump).  These aliases are found below in the FILES section and can
      also be obtained by issuing

      apparix --shell-examples

      Suppose your user name is eez and your home directory is /home/eez.  You
      often  visit  a  directory called /home/eez/cvs/xyz/tfa/faq/zut/bar/foo.
      This is how to create and use a bookmark for foo

      /home/eez/cvs/xyz/tfa/faq/zut/bar/foo> bm foo
      added: foo -> /home/eez/cvs/xyz/tfa/faq/zut/bar/foo
      /home/eez/cvs/xyz/tfa/faq/zut/bar/foo> cd
      /home/eez> to foo
      /home/eez/cvs/xyz/tfa/faq/zut/bar/foo>

      If one bookmarks a directory by its trailing component  as  happened  in
      this  case,  it is not necessary to specify the mark. By default apparix
      will use the trailing component as the mark. So

      /home/eez/cvs/xyz/tfa/faq/zut/bar/foo> bm
      added: foo -> /home/eez/cvs/xyz/tfa/faq/zut/bar/foo

      gives the same result.

      Another scenario is where you have some directory that contains  a  lar‐
      gish number of subdirectories, all of which you would like to have book‐
      marked.  If the  subdirectories  have  distinctive  names	 this  can  be
      achieved	in one fell swoop by marking the parent directory as a portal.
      This is similar to adding the parent directory to the CDPATH environment
      variable,	 except	 that  apparix bookmarks are not part of the cd names‐
      pace. It is argued in NOTES that this is a good thing.  Consider this:

      /home/cvs/bagger/boemel/mcl/mcl/src> ls
      alien/	   CVS/		impala/	     Makefile.am  README       shmcx/
      attic/	   giraffe/	lib/	     Makefile.in  shcl/	       shmx/
      contrib/	   gmon.out	Makefile     mcl/	  shmcl/       taurus/

      Some of the subdirectories have not-so-distinct names  such  as  contrib
      and  attic,  but they happen to be the directories least visited.	 Issu‐
      ing:

      /home/cvs/bagger/boemel/mcl/mcl/src> portal
      [apparix] expanded 1 portal to 12 destinations

      yields all of the subdirectories as destinations bookmarked by the  last
      component of their path name.  Incidentally, directory names such as CVS
      can be explicitly excluded from expansion	 by  setting  the  environment
      variable APPARIXEXCLUDE appropriately - refer to section ENVIRONMENT.

      Bookmarks	 resulting  from  portal  expansion  are  kept	in  a separate
      resource file (see FILES). Portal expansions can be recreated by issuing

      apparix --rehash

      This is useful to reflect a change in  the  directory  naming  structure
      underneath a portal.

  duplicate resolution
      Apparix  allows  identical  bookmarks  to	 point to different locations.
      When asked to visit such a bookmark it will by default present a list of
      options.

      The  -favour <list> option can be used to automate resolution. <list> is
      a sequence of single characters, described further below.	 The order  in
      which  they  are	given  denote  the order in which resolution rules are
      applied. This option is typically used in the definition of the to func‐
      tion/alias or in the bash completion code.

      The  -pick <num>	option	is  used  to resolve to a particular directory
      directly. This is useful when you already know where you want to go, and
      typically	 used for the now bookmark in conjunction with the bash whence
      function. Use whence now to see an indexed list of now bookmarks. It  is
      possible	to go to the desired directory by entering the bookmark index.
      It is possible to bypass the selection step by specifying whence now N.

      Duplicates are allowed because it can be useful to overwrite a  bookmark
      with a new location. The old bookmark is kept as a matter of policy. Use
      -sm to explicitly squash duplicates.

      l level; prefer paths with fewer components.

      L reverse of the above.

      o bookmark order; prefer older entries.  Entries	appearing  earlier  in
	the  file  are	considered  older, but the actual date of creating the
	bookmark is not stored.	 Refer to editing bookmarks for more  informa‐
	tion.

      O reverse of the above.

      r regular first; prefer regular bookmarks over portal expansion.

      R reverse of the above.

      If  there	 are  still  ties  after the specified rules have been applied
      apparix will simply take the first matching option. This behaviour  can‐
      not  be further specified as the program uses a non-stable ordering rou‐
      tine.

      It is an absolute prerequisite that -favour is used in the bash  comple‐
      tion  code.  Otherwise  completion will fail (for a duplicated bookmark)
      while apparix is waiting for input. Refer to the tab completion descrip‐
      tion below.

  subdirectory specification
      When  jumping  (apparating)  you	can specify an additional subdirectory
      after the bookmark. Apparix will append the subdirectory to the destina‐
      tion.

      This is useful for projects with directory nodes corresponding with ver‐
      sions. Assume you have a directory structure such as this:

	 /x/y/z/OpusMagnum/v1/
	 /x/y/z/OpusMagnum/v2/
	 /x/y/z/OpusMagnum/v3/

      It is probably easiest to simply bookmark the  OpusMagnum	 directory  in
      some  way	 (say with bookmark om). You can then issue 'to om v2' to jump
      to OpusMagnum/v2. This is more flexible and maintainable	than  creating
      bookmarks om1, om2, om3.	One could add OpusMagnum as a portal, but with
      generic names such as v1 this is not a very extendible approach.

      See also the tab completion description below - it is possible  to  tab-
      complete on subdirectories of the apparix jump directory.

  tab completion
      The  bash	 tab completion code does two things. First, it is possible to
      tab-complete on apparix bookmarks themselves, showing a listing  of  all
      available bookmarks (or iterating through them in cyclic mode, depending
      on your bash settings). Second, once a bookmark has been given tab  com‐
      pletion  will  list or iterate over all the subdirectories of the direc‐
      tory associated with that bookmark. Specifying a string after the	 book‐
      mark will limit tab-completion to directories matching the shell-pattern
      in string.  Very useful.

      Be careful to not remove the -favour list option from the	 bash  comple‐
      tion code. It is necessary to resolve duplicate bookmarks.

  editing bookmarks
      Apparix appends new bookmarks to the end of the .apparixrc file. Nothing
      stops you from editing the file, and this is in fact recommended if  for
      example you need to get rid of a bookmark and neither of -purge, -purge-
      mark, -sd, -sm fulfills your needs. It was an easy design choice not  to
      equip apparix with editor capabilities.

  copying and moving files
      It  is  straightforward  to  copy	 or  move  files to locations known by
      apparix. Examples:

      BASH and variants
	 cp FOO $(apparix zoem)
	 mv BAR $(apparix zoem doc)
	 mv BAR $(apparix zoem doc)/test

      CSH and variants
	 cp FOO `apparix zoem`
	 mv BAR `apparix zoem doc`/test

  listing bookmarks
      Simply issuing apparix gives you a list of bookmarks grouped into	 three
      categories,  portals,  expansions,  and  bookmarks. Use the -d option to
      dump the resource file to STDOUT exactly as it is. This  can  be	useful
      when  you intend to use the -u num option to remove bookmarks or portals
      that were most recently added.

      Use -l to list all available  jumps  without  their  destinations.   The
      jumps  are  grouped  into	 expansions resulting from portals and regular
      bookmarks.

  replacing cd
      With the supplied definition(s) of to, apparix will  first  see  whether
      the  mark is the name of a directory, accessible from the current direc‐
      tory.  A directory is accessible if it would be a valid argument to  cd,
      so  it  need not necessarily be a subdirectory of the current directory.
      If the mark is not an accessible directory, apparix will then try to  do
      a	 lookup	 of  the  mark	in  the	 bookmark files. This behaviour can be
      inverted to do the lookup first and the  current	directory  thereafter.
      Both  modes  can	be used to make to a drop-in replacement for cd. Addi‐
      tionally and again similar to cd, 'to -' will take you to	 the  previous
      directory,  and  specifying  to  without arguments will take you to your
      home directory.

      The bash completion code acts accordingly, and should transparently com‐
      plete on both marks and directories.

  OPTIONS
      For bookmarking and jumping apparix is best invoked by using the aliases
      (tcsh-variants) or functions (sh/bash) listed in FILES.  Apparix	has  a
      few  options  that  are useful for pruning, squashing and rehasing book‐
      marks. These are best issued by invoking apparix directly.

      If you are interested in marks or destinations matching a	 certain  pat‐
      tern,  simply  issue  apparix without arguments and pipe it through your
      program of choice.

      Unary options (those without arguments) usually start with  two  hyphens
      except  for standardized options such as -h.  Options that take an argu‐
      ment can be converted  to	 a  unary  key=value  notation,	 e.g.  -purge-
      mark foo is equivalent to --purge-mark=foo.

      When invoked without arguments apparix will simply dump its bookmarks.

      --add-mark (add jump bookmark)
	This  options expects trailing [mark [destination]] argument(s).  Both
	arguments are optional. If a single argument is	 given	it  is	inter‐
	preted	as  a bookmark name to be mapped to the current directory.  If
	two arguments are given the last  argument  is	taken  as  the	target
	directory.  If	no  argument  is given apparix will enlist the current
	directory as a target bookmarked by  the  trailing  component  of  the
	directory path.

      --add-portal (add portal bookmark)
	This  option  enlists a directory as a portal and adds all subdirecto‐
	ries as bookmarks. The name of the bookmark is simply the name of  the
	subdirectory.  By  default the current directory is added as a portal.
	An optional trailing argument will override this behaviour and instead
	be interpreted as the portal location.

      --try-current-first (try current directory before lookup)
	This  option  is  useful  in  the definition of the to wrapper. Before
	attempting any lookup of the mark, apparix tests whether the  supplied
	mark  exists  as  a subdirectory in the current directory. If it does,
	the mark is simply expanded to itself.

      --try-current-last (try current directory if lookup fails)
	This option is useful in the definition of the to wrapper.  If	lookup
	of the mark fails, apparix tests whether the supplied mark exists as a
	subdirectory in the current directory. If it does, the mark is	simply
	expanded to itself.

      --notify-current (notify if current directory is used)
	This  option is useful in the definition of the bf wrapper in conjunc‐
	tion with either --try-current-first or	 --try-current-last.   If  the
	mark  is  found	 as  a	subdirectory in the current directory, apparix
	notifies the user of this fact (on the diagnostic stream).

      -sm <mar> (squash repeated marks)
	Apparix will squash bookmarks with mark <mark>.	 This is useful when a
	mark  points  to  a versioned project, and the project is updated to a
	new version and a new directory.

	Apparix will by default keep the last one occurring  in	 the  resource
	file  (corresponding with -favour O). This option respects the -favour
	option if given. Duplicating an already existing mark  can  be	useful
	when  it  identifies  a	 project  for  which  the underlying directory
	changes every once in a while (e.g. the	 project  is  downloaded  from
	external  sources  and	comes  with  version  information).  It is not
	strictly necessary to squash bookmarks since to functions/macros  that
	are  equipped with the -favour option will generally resolve duplicate
	matches.

      -sd <mark> (squash repeated destinations)
	All other bookmarks with the same destination as <mark>	 are  removed.
	This  is  useful  when a given destination has acquired multiple book‐
	marks and you decide to settle on a favourite.

      -lm <mark> (list bookmarks with this mark)
	It lists all bookmarks <mark> (noting that it may  point  to  multiple
	locations).

      -ld <mark> (list repeated destinations)
	This  lists all bookmarks <mark> (noting that it may point to multiple
	locations) and additionally lists all other bookmarks that  share  the
	destination  with  any of the first bookmarks. This allows one to pre‐
	dict the effect of issuing apparix -sd <mark>.

      -purge pat (delete bookmarks)
	This deletes bookmarks where destination  matches  pat.	  All  deleted
	bookmarks  are	printed to STDOUT. Thus if you regret deleting a book‐
	mark it is easy to  add	 it  back.  Portal  specifications  are	 never
	affected.

      -purge-mark (pat)
	This  deletes bookmarks where mark matches pat.	 Portal specifications
	are never affected.

      -d (dump resource file to STDOUT)
	Dump resource file to STDOUT.

      -l (list available jumps)
	List available jumps paragraph-style. Portal specifications themselves
	are excluded, and regular jumps and jumps resulting from portal expan‐
	sions are listed under different headers.

      -u <num> (remove last <num> additions)
	Remove last <num> additions. Portal specifications and	regular	 jumps
	are treated alike.

      --rehash (re-expand portal bookmarks)
	Apparix	 will  reread the resource file and reexpand portal locations.
	Useful if directories have been added, renamed, or removed.  Refer  to
	section	 ENVIRONMENT  for  the	effect	that  the environment variable
	APPARIXEXCLUDE has on portal expansion.

      -favour <list> (set duplicate resolution policy)
      -pick <num> (immediate duplicate resolution)
	These options have a section to themselves. Refer to duplicate resolu‐
	tion.

      --cwd (use getcwd(3), not pwd(1))
	By  default aparix uses the program pwd(1) rather than the system call
	getcwd(3). On some systems it was found that  the  latter  results  in
	paths  that  contain machine-specific mount components.	 Appparix will
	use getcwd(3) when --cwd is used.

      --shell-examples (output example macros)
	This outputs example macros. They are also listed in the FILES section
	though.

      --bu (create backup of the resource file)
	This creates the backup file in .apparixrc.bu.

      -bu fname (create backup of the resource file)
	This creates the backup file in fname. Use -d or -bu - to dump to STD‐
	OUT.

      -h (show synopsis)
      --apropos (show synopsis)
	print synopsis of all options

  ENVIRONMENT
      APPARIXEXCLUDE
	This variable specifies exclusion behaviour when portals are  expanded
	with the --rehash option.  It has the following syntax:

	   <[:,][<string>]>+

	That  is,  a  list  of	names  with each name preceded by a colon or a
	comma.	A colon indicates that <string> triggers exclusion  of	direc‐
	tory  names for which the trailing component is identical to <string>.
	A comma indicates that <string> triggers exclusion of directory	 names
	for  which  the	 trailing  component contains <string> as a substring.
	Consider:

	   export APPARIXEXCLUDE=:CVS:lib,tmp	     # A - example
	   export APPARIXEXCLUDE=,		     # B - curiosity

	The first excludes directory names CVS and lib and any directory  name
	having	tmp  as a substring.  The second example will effectively dis‐
	able portals, as it speficies the empty string which is a substring of
	all strings.

      APPARIXTAG
	This  variable,	 if set, is incorporated into the names of the apparix
	resource files. By default these are  .apparixrc  and  .apparixexpand.
	When  APPARIXTAG  is  set  to  <tag>  they  become .<tag>apparixrc and
	.<tag>apparixexpand.  This can be used e.g. to maintain different sets
	of bookmarks on different host machines.

      APPARIXLOG
	This  variable, if set, is interpreted as the name of a log file.  The
	log file keeps track of all newly added bookmarks and portals  without
	ever  deleting anything, in the same format as the .apparixrc file. If
	this variable is not set nothing is tracked.

      APPARIXPURGE
	This changes the way apparix dumps purged  bookmarks  to  STDOUT.   By
	default	 they are dumped as command lines that will reimport the book‐
	marks if issued (i.e. cut and pasted).	By setting this variable to  1
	purged bookmarks are dumped in the format used in the .apparixrc file.

  FILES
      You  should use aliases or functions to make apparix really useful.  Get
      them from apparix by giving it the --shell-examples option, or from fur‐
      ther  below.   Note the fragment that provides to argument completion in
      bash.

      $HOME/.apparixrc
	This is the primary resource file. There is usually no need to edit it
	by  hand.  Sometimes  it  can  be  useful to edit by hand to remove an
	unwanted bookmark; refer to editing bookmarks.

      $HOME/.apparixrc.bu
	Apparix creates a back-up file whenever it is asked to remove  entries
	from it. Refer to editing bookmarks for options inducing removal.  You
	can explicitly require a backup to  be	made  by  either  of  --bu  or
	-bu fname.

      $HOME/.apparixexpand
	This  contains	bookmarks that are expanded from portals.  A portal is
	simply some directory. The names of all subdirectories	are  taken  as
	bookmarks that point to those subdirectories.  This file can be recre‐
	ated by issuing

	apparix --rehash

      $HOME/.bashrc
      $HOME/.tcshrc
      $HOME/.cshrc
	Add the code you need to the appropriate rc file. The macros and func‐
	tions below point cd(1) in the right direction.

      BASH-style functions
      ---
      function to () {
	if test "$2"; then
	  cd "$(apparix --try-current-first -favour rOl "$1" "$2" || echo .)"
	elif test "$1"; then
	  if test "$1" == '-'; then
	    cd -
	  else
	    cd "$(apparix --try-current-first -favour rOl "$1" || echo .)"
	  fi
	else
	  cd $HOME
	fi
      }
      function bm () {
	if test "$2"; then
	  apparix --add-mark "$1" "$2";
	elif test "$1"; then
	  apparix --add-mark "$1";
	else
	  apparix --add-mark;
	fi
      }
      function portal () {
	if test "$1"; then
	  apparix --add-portal "$1";
	else
	  apparix --add-portal;
	fi
      }
      # function to generate list of completions from .apparixrc
      function _apparix_aliases ()
      { cur=$2
	dir=$3
	COMPREPLY=()
	nullglobsa=$(shopt -p nullglob)
	shopt -s nullglob
	if let $(($COMP_CWORD == 1)); then
	  # now cur=<apparix mark> (completing on this) and dir='to'
	  # Below will not complete on subdirectories. swap if so desired.
	  # COMPREPLY=( $( cat $HOME/.apparix{rc,expand} | grep "j,.*$cur.*," | cut -f2 -d, ) )
	  COMPREPLY=( $( (cat $HOME/.apparix{rc,expand} | grep "\<j," | cut -f2 -d, ; ls -1p | grep '/$' | tr -d /) | grep "\<$cur.*" ) )
	else
	  # now dir=<apparix mark> and cur=<subdirectory-of-mark> (completing on this)
	  dir=`apparix --try-current-first -favour rOl $dir 2>/dev/null` || return 0
	  eval_compreply="COMPREPLY=( $(
	    cd "$dir"
	    \ls -d $cur* | while read r
	    do
	      [[ -d "$r" ]] &&
	      [[ $r == *$cur* ]] &&
		echo \"${r// /\\ }\"
	    done
	  ) )"
	eval $eval_compreply
	fi
	$nullglobsa
	return 0
      }
      # command to register the above to expand when the 'to' command's args are
      # being expanded
      complete -F _apparix_aliases to
      ---
      CSH-style aliases
      ---
      # The outcommented alias does not supplant cd, the other one does.
      # alias to    'cd `(apparix -favour rOl \!* || echo -n .)`'
      alias to '(test "x-" =  "x\!*") && cd - || (test "x" !=  "x\!*") && cd `(apparix --try-current-first -favour rOl \!* || echo -n .)` || cd'
      alias bm	 'apparix --add-mark \!*'
      alias portal 'apparix --add-portal \!*'
      ---

      More elaborate setups are possible. This CSH-style alias:

      alias to '(test "x" !=  "x\!*") && cd `(apparix -favour rOl \!* || echo -n .)` || apparix -l'

      lists all available jumps if invoked without arguments.

  NOTES
      Below  follow  some  comments on other approaches to file system naviga‐
      tion.  HISTORY explains the difference between the venerable cdargs pro‐
      gram and apparix.

      CDPATH  is  only useful in cases where a given directory has subdirecto‐
      ries with distinctive names. It does not usually scale well  when	 there
      are more than a few paths in CDPATH.

      Some people use aliases to jump to often visited directories.  I was one
      of them for a period of ten years. The fact is, those aliases  are  cum‐
      bersome  to  create  and remove and they clutter up the alias namespace.
      They can clash with executable names when	 the  alias  includes  the  cd
      part.  This  sometimes prohibits one from assigning the logical bookmark
      to a given location, especially when one has a lot of source code	 loca‐
      tions.  They can clash with directory names when the aliases just expand
      to the location. This again means that sometimes a  location  cannot  be
      assigned its logical bookmark.  I have found that setting cd jumps aside
      in their own namespace improves file system navigation by a  large  fac‐
      tor.

      It  is  also  possible to create symlinks to often visited files. Again,
      creation and removal of these are cumbersome.  One could of course  cre‐
      ate  shell  functions  with  a similar interface to apparix or cdargs to
      handle the symlink lifecycle.  On Linux Weekly News nix suggested to put
      these  symlinks  in a single directory and add that directory to CDPATH.
      This is quite a neat trick and effectively creates a bookmark navigation
      system.

      Still  there are problems with the above approach.  One problem with the
      symlink approach is that they are a bit awkward to edit. One could  make
      a utility to wrap around the problem, but in the end the directory-with-
      symlinks would functionally be the same as apparix's .apparixrc resource
      file,  only  more	 of  a	kludge.	  Another problem is that symlinks are
      awkard when traversing the file system. They confuse the notion of  par‐
      ent directory and 'cd ..' mostly does the unexpected. Sometimes '..' has
      a different meaning to cd than it has to	another	 application,  as  one
      will  trace  back	 symlinks  and	the  other will not.  Finally, a minor
      objection is that I find it convenient to have bookmarks in  a  separate
      namespace	 than  that  of	 cd(1). Jumps are magical and it is natural to
      invoke them by a different method. This is in fact how apparix  acquired
      its  CDPATH  behaviour. I used CDPATH to jump to a few particular source
      directories with distinct names that  lay	 deeply	 hidden	 in  some  CVS
      directory.  Once	I  started  using  apparix however, I would mistakenly
      issue to rather than cd to jump to those locations. My brain  classified
      both types of jump in the same category.

      Apparix  (and  cdargs)  have another use besides jumping, namely annota‐
      tion. Whenever I end up in an esoteric part of the file system and  need
      to make a quick note of the location, I simply bookmark it.

      On  SlashDot,  that  eternal  source of wisdom or alternatively the geek
      wheel of suffering, Clueless Moron offered the following gems.

	 mk() { eval ${1:-MKPWD}=\"`pwd`\"; }
	 rt() { eval cd \"\$${1:-MKPWD}\";pwd; }

	 # type "mk" (as in "mark") and "rt" (as in "return") to mark
	 # a directory and later go back to it.
	 # Or give it a name: do "mk foo", and later on "rt foo"

      This of course is a per-session mechanism, but noteworthy for  its  sim‐
      plicity.	I  am not sure whether csh-style shells could offer an equiva‐
      lent.

      A feature shared by apparix and cdargs is that adding a bookmark immedi‐
      ately  takes  effect  in	all  shells.  There  is no need to source some
      resource file, as the applications do this everytime they	 are  invoked.
      It is fast, do not worry.

  BUGS
      The  resource  file  parsing  code  thinks that parentheses are special.
      Also records are currently separated  by	commas.	 Accordingly,  apparix
      will hitch if a path name contains a parenthesis or a comma.

  AUTHOR
      Stijn van Dongen.

  THANKS
      Stefan Kamphausen wrote cdargs, the inspiration for apparix.

      Sitaram  Chamarty fixed up some of the existing bash code, and added the
      tab completion part (basing this on similar code in cdargs). He does not
      garantuee	 predictable or even pretty results if there are spaces in the
      directory names which you attempt to complete. AUTHOR would like to sub‐
      mit  that	 spaces	 in  path names are evil, and that the completion code
      seems to work in their evil presence anyway. Just don't  put  commas  in
      path names.

      The autotooled build environment was modified from a template written by
      Joost van Baal.

      Several people suggested to enable apparix to merge accessible  directo‐
      ries and marks, but Matias Piipari phrased it the most convincingly.

  HISTORY
      Apparix  was created to optimize a scenario that cdargs does not support
      very well, namely where the mark (called needle  in  cdargs)  is	always
      known.  As  additional features apparix supports CDPATH-style behaviour,
      derived subdirectory specification, and transparent treatment  of	 book‐
      marks and directories, all integrated with bash tab completion. In other
      respects apparix is a much simpler application. cdargs offers menu-based
      navigation  of the file system and the bookmark list, which apparix does
      not.

  apparix 1.004, 11-062		    3 Mar 2011			      apparix(1)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net