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

FreeBSD Manual Pages

  
 
  

home | help
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 ex-
      amples, 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://mi-
      cans.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  ap-
      parix  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 de-
      fault the	bash completion	code takes into	account	both bookmarks and di-
      rectories.

      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  ad-
      ditionally  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  ex-
      plains  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 name-
      space. 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 re-
      source file (see FILES). Portal expansions can be	recreated by issuing

      apparix --rehash

      This is useful to	reflect	a change in the	directory naming structure un-
      derneath 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 ap-
      plied. 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 di-
      rectly. 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 ap-
      parix will simply	take the first matching	option.	This behaviour	cannot
      be further specified as the program uses a non-stable ordering routine.

      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 af-
      ter  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  ap-
      parix. 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  in-
      verted to	do the lookup first and	the current directory thereafter. Both
      modes can	be used	to make	to a drop-in replacement for cd.  Additionally
      and again	similar	to cd, 'to -' will take	you to the previous directory,
      and specifying to	without	arguments will take you	to  your  home	direc-
      tory.

      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 di-
	rectory. If no argument	is given apparix will enlist the  current  di-
	rectory	as a target bookmarked by the trailing component of the	direc-
	tory 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  at-
	tempting  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  no-
	tifies 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 ex-
	ternal 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 af-
	fected.

      -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  AP-
	PARIXEXCLUDE 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 de-
	fault 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  un-
	wanted 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  ob-
      jection  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 in-
      voke  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 di-
      rectory. 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  re-
      source  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)

Want to link to this manual page? Use this URL:
<
https://www.freebsd.org/cgi/man.cgi?query=apparix&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help