| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| 2 |
<html> |
| 3 |
<!-- Copyright (c) 2011 Stijn van Dongen --> |
| 4 |
<head> |
| 5 |
<meta name="keywords" content="manual"> |
| 6 |
<style type="text/css"> |
| 7 |
/* START aephea.base.css */ |
| 8 |
body |
| 9 |
{ text-align: justify; |
| 10 |
margin-left: 0%; |
| 11 |
margin-right: 0%; |
| 12 |
} |
| 13 |
a:link { text-decoration: none; } |
| 14 |
a:active { text-decoration: none; } |
| 15 |
a:visited { text-decoration: none; } |
| 16 |
a:link { color: #1111aa; } |
| 17 |
a:active { color: #1111aa; } |
| 18 |
a:visited { color: #111166; } |
| 19 |
a.local:link { color: #11aa11; } |
| 20 |
a.local:active { color: #11aa11; } |
| 21 |
a.local:visited { color: #116611; } |
| 22 |
a.intern:link { color: #1111aa; } |
| 23 |
a.intern:active { color: #1111aa; } |
| 24 |
a.intern:visited { color: #111166; } |
| 25 |
a.extern:link { color: #aa1111; } |
| 26 |
a.extern:active { color: #aa1111; } |
| 27 |
a.extern:visited { color: #661111; } |
| 28 |
a.quiet:link { color: black; } |
| 29 |
a.quiet:active { color: black; } |
| 30 |
a.quiet:visited { color: black; } |
| 31 |
div.verbatim |
| 32 |
{ font-family: monospace; |
| 33 |
margin-top: 1em; |
| 34 |
margin-bottom: 1em; |
| 35 |
font-size: 10pt; |
| 36 |
margin-left: 2em; |
| 37 |
white-space: pre; |
| 38 |
} |
| 39 |
div.indent |
| 40 |
{ margin-left: 8%; |
| 41 |
margin-right: 0%; |
| 42 |
} |
| 43 |
.right { text-align: right; } |
| 44 |
.left { text-align: left; } |
| 45 |
.nowrap { white-space: nowrap; } |
| 46 |
.item_leader |
| 47 |
{ position: relative; |
| 48 |
margin-left: 8%; |
| 49 |
} |
| 50 |
.item_compact { position: absolute; vertical-align: baseline; } |
| 51 |
.item_cascade { position: relative; } |
| 52 |
.item_leftalign { text-align: left; } |
| 53 |
.item_rightalign |
| 54 |
{ width: 2em; |
| 55 |
text-align: right; |
| 56 |
} |
| 57 |
.item_compact .item_rightalign |
| 58 |
{ position: absolute; |
| 59 |
width: 52em; |
| 60 |
right: -2em; |
| 61 |
text-align: right; |
| 62 |
} |
| 63 |
.item_text |
| 64 |
{ position: relative; |
| 65 |
margin-left: 3em; |
| 66 |
} |
| 67 |
.smallcaps { font-size: smaller; text-transform: uppercase } |
| 68 |
acronym.ucase { font-size: smaller; text-transform: uppercase } |
| 69 |
abbr.ucase { font-size: smaller; text-transform: uppercase } |
| 70 |
/* END aephea.base.css */ |
| 71 |
body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; } |
| 72 |
body |
| 73 |
{ text-align: justify; |
| 74 |
margin-left: 8%; |
| 75 |
margin-right: 8%; |
| 76 |
} |
| 77 |
</style> |
| 78 |
<title>apparix, augmenting the shell with directory bookmarks</title> |
| 79 |
</head> |
| 80 |
<body> |
| 81 |
<p style="text-align:right"> |
| 82 |
3 Mar 2011 |
| 83 |
<a class="local" href="apparix.ps"><b>apparix</b></a> |
| 84 |
1.004, 11-062 |
| 85 |
</p> |
| 86 |
<div class=" itemize " style="margin-top:1em; font-size:100%"> |
| 87 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">1.</div></div> |
| 88 |
<div class=" item_text " style="margin-left:4em"> |
| 89 |
<a class="intern" href="#name">NAME</a> |
| 90 |
</div> |
| 91 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">2.</div></div> |
| 92 |
<div class=" item_text " style="margin-left:4em"> |
| 93 |
<a class="intern" href="#synopsis">SYNOPSIS</a> |
| 94 |
</div> |
| 95 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">3.</div></div> |
| 96 |
<div class=" item_text " style="margin-left:4em"> |
| 97 |
<a class="intern" href="#gs">GETTING STARTED</a> |
| 98 |
</div> |
| 99 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">4.</div></div> |
| 100 |
<div class=" item_text " style="margin-left:4em"> |
| 101 |
<a class="intern" href="#description">DESCRIPTION</a> |
| 102 |
</div> |
| 103 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">5.</div></div> |
| 104 |
<div class=" item_text " style="margin-left:4em"> |
| 105 |
<a class="intern" href="#dup">duplicate resolution</a> |
| 106 |
</div> |
| 107 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">6.</div></div> |
| 108 |
<div class=" item_text " style="margin-left:4em"> |
| 109 |
<a class="intern" href="#sub">subdirectory specification</a> |
| 110 |
</div> |
| 111 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">7.</div></div> |
| 112 |
<div class=" item_text " style="margin-left:4em"> |
| 113 |
<a class="intern" href="#tab">tab completion</a> |
| 114 |
</div> |
| 115 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">8.</div></div> |
| 116 |
<div class=" item_text " style="margin-left:4em"> |
| 117 |
<a class="intern" href="#edit">editing bookmarks</a> |
| 118 |
</div> |
| 119 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">9.</div></div> |
| 120 |
<div class=" item_text " style="margin-left:4em"> |
| 121 |
<a class="intern" href="#mov">copying and moving files</a> |
| 122 |
</div> |
| 123 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">10.</div></div> |
| 124 |
<div class=" item_text " style="margin-left:4em"> |
| 125 |
<a class="intern" href="#list">listing bookmarks</a> |
| 126 |
</div> |
| 127 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">11.</div></div> |
| 128 |
<div class=" item_text " style="margin-left:4em"> |
| 129 |
<a class="intern" href="#cd">replacing cd</a> |
| 130 |
</div> |
| 131 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">12.</div></div> |
| 132 |
<div class=" item_text " style="margin-left:4em"> |
| 133 |
<a class="intern" href="#options">OPTIONS</a> |
| 134 |
</div> |
| 135 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">13.</div></div> |
| 136 |
<div class=" item_text " style="margin-left:4em"> |
| 137 |
<a class="intern" href="#environment">ENVIRONMENT</a> |
| 138 |
</div> |
| 139 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">14.</div></div> |
| 140 |
<div class=" item_text " style="margin-left:4em"> |
| 141 |
<a class="intern" href="#files">FILES</a> |
| 142 |
</div> |
| 143 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">15.</div></div> |
| 144 |
<div class=" item_text " style="margin-left:4em"> |
| 145 |
<a class="intern" href="#notes">NOTES</a> |
| 146 |
</div> |
| 147 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">16.</div></div> |
| 148 |
<div class=" item_text " style="margin-left:4em"> |
| 149 |
<a class="intern" href="#bugs">BUGS</a> |
| 150 |
</div> |
| 151 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">17.</div></div> |
| 152 |
<div class=" item_text " style="margin-left:4em"> |
| 153 |
<a class="intern" href="#author">AUTHOR</a> |
| 154 |
</div> |
| 155 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">18.</div></div> |
| 156 |
<div class=" item_text " style="margin-left:4em"> |
| 157 |
<a class="intern" href="#thanks">THANKS</a> |
| 158 |
</div> |
| 159 |
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">19.</div></div> |
| 160 |
<div class=" item_text " style="margin-left:4em"> |
| 161 |
<a class="intern" href="#history">HISTORY</a> |
| 162 |
</div> |
| 163 |
</div> |
| 164 |
|
| 165 |
<a name="name"></a> |
| 166 |
<h2>NAME</h2> |
| 167 |
<p style="margin-bottom:0" class="asd_par"> |
| 168 |
apparix — augmenting cd with bookmarks</p> |
| 169 |
|
| 170 |
<a name="synopsis"></a> |
| 171 |
<h2>SYNOPSIS</h2> |
| 172 |
<p style="margin-bottom:0" class="asd_par"> |
| 173 |
Apparix allows you to bookmark directories and later jump to them using the mark. |
| 174 |
By default apparix acts as a replacement for <i>cd</i> and can be used in the |
| 175 |
same manner, including the special behaviour for <i>cd</i> without argument |
| 176 |
and <i>cd</i> <tt>-</tt>. |
| 177 |
It is possible to directly jump to subdirectories of a bookmarked directory. |
| 178 |
The contributed bash completion code facilitates completion both on |
| •179 |
bookmarks and directories, but can be adjusted to accommodate other |
| 180 |
preferences. |
| 181 |
</p> |
| 182 |
<p style="margin-bottom:0" class="asd_par"> |
| 183 |
This manual page suffers from an excess in verbosity due to the many |
| 184 |
examples, explanations of the bells and whistles, and comparisons with other |
| 185 |
approaches to bookmarking. The fundamental idea is simply that typing a |
| 186 |
string of your own choosing takes you to the directory associated with it. |
| 187 |
Apparix does little more than maintaining a list of keys and values. |
| 188 |
It obtains directory names and listings, associates |
| 189 |
path names (values) with bookmarks (keys), and has some facilities for |
| 190 |
manipulating keys and values. The functions involving apparix |
| 191 |
(<b>bm</b>, <b>to</b>, and <b>portal</b>) provide the user interface. |
| 192 |
Other functions, <b>als</b> (apparix ls) and <b>ae</b> (apparix edit) |
| 193 |
are discussed on the main apparix page <a class="extern" target="_parent" href="http://micans.org/apparix">http://micans.org/apparix</a>. |
| 194 |
</p> |
| 195 |
|
| 196 |
<a name="gs"></a> |
| 197 |
<h2>GETTING STARTED</h2> |
| 198 |
<p style="margin-bottom:0" class="asd_par"> |
| 199 |
Install apparix. This should be as easy as <tt>./configure --prefix=$HOME/local && make && make install</tt>, |
| 200 |
or perhaps a pre-packaged apparix is available for your system. |
| 201 |
Then get hold of the <b>to</b>, <b>bm</b> and <b>portal</b> shell handles. These |
| 202 |
are either aliases or functions depending on your shell. Currently csh-style |
| 203 |
shells and bash are supported. |
| 204 |
Get the ones you need preferably from |
| 205 |
<a class="extern" target="_parent" href="http://micans.org/apparix/#shell">http://micans.org/apparix/#shell</a>. For a more limited set of |
| 206 |
commands either visit the <a class="intern" href="#files">FILES</a> section, or issue <tt>apparix |
| 207 |
--shell-examples</tt>. Activate them by simply pasting them in a shell or adding |
| 208 |
them to the appropriate resource file, e.g. <tt>$HOME/.cshrc</tt> or |
| 209 |
<tt>$HOME/.bashrc</tt> (do not forget to <i>source</i> the resource file). The |
| 210 |
handles <b>to</b>, <b>bm</b> and <b>portal</b> can of course be changed to any |
| 211 |
name desired. With these preliminaries, the following is a mock-up shell |
| 212 |
navigation session. |
| 213 |
</p> |
| 214 |
<div class="verbatim"> > <b>pwd</b> |
| 215 |
/home/eez/cvs/xyz/tfa/faq/zut/bar/foo |
| 216 |
> <b>ls</b> |
| 217 |
src/ doc/ CVS/ bin/ |
| 218 |
> <b>bm xkr</b> # bookmark as xkr (funny name though) |
| 219 |
> <b>bm</b> # bookmark as foo (trailing component is default) |
| 220 |
(later) |
| 221 |
> <b>to xkr</b> # cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo |
| 222 |
(alternatively) |
| 223 |
> <b>to xkr src</b> # cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo/src |
| 224 |
(alternatively) |
| 225 |
> <b>to foo</b> # cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo |
| 226 |
|
| 227 |
(later) |
| 228 |
> <b>ls</b> |
| 229 |
aap pyu/ qua tim/ zut/ |
| 230 |
> <b>pwd</b> |
| 231 |
/home/eez/another/branch/deep/down/under |
| 232 |
> <b>portal</b> # bookmark as portal, imports tim zut pyu bookmarks |
| 233 |
added flock of 3 in portal /home/eez/another/branch/deep/down/under |
| 234 |
|
| 235 |
(later) |
| 236 |
> <b>to zut</b> # cd to /home/eez/another/branch/deep/down/under/zut |
| 237 |
|
| 238 |
(later) |
| 239 |
> <b>apparix</b> # show all bookmarks |
| 240 |
--- portals |
| 241 |
e /home/eez/another/branch/deep/down/under |
| 242 |
--- expansions |
| 243 |
j pyu /home/eez/another/branch/deep/down/under/pyu |
| 244 |
j tim /home/eez/another/branch/deep/down/under/tim |
| 245 |
j zut /home/eez/another/branch/deep/down/under/zut |
| 246 |
--- bookmarks |
| 247 |
j xkr /home/eez/cvs/xyz/tfa/faq/zut/bar/foo |
| 248 |
j foo /home/eez/cvs/xyz/tfa/faq/zut/bar/foo</div> |
| 249 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 250 |
In the last example apparix simply shows all its bookmarks. The first batch |
| 251 |
shows portals. The second batch shows secondary bookmarks expanded from |
| 252 |
portals. The third batch shows all regular bookmarks. |
| 253 |
</p> |
| 254 |
<p style="margin-bottom:0" class="asd_par"> |
| 255 |
In the default definitions of <b>to</b> it falls back to regular <i>cd</i> |
| 256 |
behaviour in case a mark is not found. This is done by instructing apparix |
| 257 |
to check whether the mark exists as the name of a directory. It is possible |
| 258 |
to do this either before or after bookmark lookup, or not at all. By default |
| 259 |
the bash completion code takes into account both bookmarks and directories. |
| 260 |
</p> |
| 261 |
<p style="margin-bottom:0" class="asd_par"> |
| 262 |
Apparix also allows subdirectory specification of bookmarked locations. If |
| 263 |
this is combined with the bash completion code it yields a powerful way of |
| 264 |
navigating container directories, i.e. directories that contain a large |
| 265 |
number of subdirectories. Refer to the <a class="intern" href="#sub">subdirectory specification</a> section. |
| 266 |
</p> |
| 267 |
<p style="margin-bottom:0"><b>Further options</b><br> |
| 268 |
<a class="intern" href="#opt--add-mark"><b>[--add-mark</b> (<i>add jump bookmark</i>)<b>]</b></a> |
| 269 |
<a class="intern" href="#opt--add-portal"><b>[--add-portal</b> (<i>add portal bookmark</i>)<b>]</b></a> |
| 270 |
<a class="intern" href="#opt-sm"><b>[-sm</b> <mark> (<i>squash repeated marks</i>)<b>]</b></a> |
| 271 |
<a class="intern" href="#opt-sd"><b>[-sd</b> <mark> (<i>squash repeated destinations</i>)<b>]</b></a> |
| 272 |
<a class="intern" href="#opt-lm"><b>[-lm</b> <mark> (<i>list bookmarks with this mark</i>)<b>]</b></a> |
| 273 |
<a class="intern" href="#opt-ld"><b>[-ld</b> <mark> (<i>list destinations with mark indirection</i>)<b>]</b></a> |
| 274 |
<a class="intern" href="#opt-favour"><b>[-favour</b> <list> (<i>duplicate resolution policy</i>)<b>]</b></a> |
| 275 |
<a class="intern" href="#opt-pick"><b>[-pick</b> <num> (<i>immediate duplicate resolution</i>)<b>]</b></a> |
| 276 |
<a class="intern" href="#opt-purge"><b>[-purge</b> pat (<i>delete bookmarks</i>)<b>]</b></a> |
| 277 |
<a class="intern" href="#opt-purge-mark"><b>[-purge-mark</b> (<i>pat</i>)<b>]</b></a> |
| 278 |
<a class="intern" href="#opt-d"><b>[-d</b> (<i>dump resource file to STDOUT</i>)<b>]</b></a> |
| 279 |
<a class="intern" href="#opt-l"><b>[-l</b> (<i>list available jumps</i>)<b>]</b></a> |
| 280 |
<a class="intern" href="#opt-u"><b>[-u</b> <num> (<i>remove last <num> additions</i>)<b>]</b></a> |
| 281 |
<a class="intern" href="#opt--rehash"><b>[--rehash</b> (<i>re-expand portal bookmarks</i>)<b>]</b></a> |
| 282 |
<a class="intern" href="#opt--bu"><b>[--bu</b> (<i>create backup of resource file</i>)<b>]</b></a> |
| 283 |
<a class="intern" href="#opt-bu"><b>[-bu</b> <fname> (<i>create backup in <fname></i>)<b>]</b></a> |
| 284 |
<a class="intern" href="#opt--cwd"><b>[--cwd</b> (<i>use getcwd(3), not pwd(1)</i>)<b>]</b></a> |
| 285 |
<a class="intern" href="#opt--shell-examples"><b>[--shell-examples</b> (<i>output example macros</i>)<b>]</b></a> |
| 286 |
</p> |
| 287 |
|
| 288 |
<a name="description"></a> |
| 289 |
<h2>DESCRIPTION</h2> |
| 290 |
<p style="margin-bottom:0" class="asd_par"> |
| 291 |
Apparix combines the properties of the |
| 292 |
<a target="_parent" class="extern" href="http://www.skamphausen.de/cgi-bin/ska/CDargs">cdargs</a> utility and the |
| 293 |
CDPATH shell mechanism for fast navigation through the file system. It can |
| 294 |
additionally act as the regular <i>cd</i> command. It is especially useful for |
| 295 |
visiting and documenting both often- and rarely-used locations. Apparix |
| 296 |
enables you to attach marks to locations and jump to those locations by |
| 297 |
loading the mark. Marking, unmarking and jumping are simple operations that |
| 298 |
are performed in the shell. All actions take effect immediately in all |
| 299 |
shells running. By setting up convenient aliases for marking and jumping |
| 300 |
the file system can be navigated in a fast and intuitive manner. The |
| 301 |
<a class="intern" href="#files">FILES</a> section lists aliases for csh-type shells and functions for |
| 302 |
bash, including the setup to equip the <b>to</b> function with argument |
| 303 |
completion in bash. |
| 304 |
</p> |
| 305 |
<p style="margin-bottom:0" class="asd_par"> |
| 306 |
This section contains some examples of the most common uses |
| 307 |
of apparix. |
| 308 |
<a class="intern" href="#options">OPTIONS</a> contains a list of additional options available |
| 309 |
for listing, pruning, and squashing bookmarks.</p> |
| 310 |
<p style="margin-bottom:0" class="asd_par"> |
| 311 |
<a class="intern" href="#notes">NOTES</a> features a brief discussion of the advantages |
| 312 |
of apparix over other approaches such as setting up aliases for |
| 313 |
often visited directories, using symlinks, CDPATH, or a combination |
| 314 |
of these. <a class="intern" href="#history">HISTORY</a> explains the difference between |
| 315 |
cdargs and apparix. |
| 316 |
The sections <a class="intern" href="#dup">duplicate resolution</a>, <a class="intern" href="#sub">subdirectory specification</a>, <a class="intern" href="#tab">tab completion</a>, |
| 317 |
<a class="intern" href="#mov">copying and moving files</a>, <a class="intern" href="#list">listing bookmarks</a>, and <a class="intern" href="#cd">replacing cd</a> |
| 318 |
further below are also recommended reading.</p> |
| 319 |
<p style="margin-bottom:0" class="asd_par"> |
| 320 |
Apparix works in a manner similar to cdargs. One usually invokes |
| 321 |
apparix by using pre-defined aliases. Here they will be called <b>bm</b> for |
| 322 |
bookmark, <b>portal</b> for a CDPATH-style bookmark and <b>to</b> for initiating |
| 323 |
an apparition (aka jump). |
| 324 |
These aliases are found below in the <a class="intern" href="#files">FILES</a> |
| 325 |
section and can also be obtained by issuing</p> |
| 326 |
<div class="verbatim">apparix --shell-examples</div> |
| 327 |
<p style="margin-bottom:0" class="asd_par"> |
| 328 |
Suppose your user name is <i>eez</i> and your home directory is <tt>/home/eez</tt>. |
| 329 |
You often visit a directory called |
| 330 |
<tt>/home/eez/cvs/xyz/tfa/faq/zut/bar/foo</tt>. |
| 331 |
This is how to create and use a bookmark for foo</p> |
| 332 |
<div class="verbatim">/home/eez/cvs/xyz/tfa/faq/zut/bar/foo> <b>bm foo</b> |
| 333 |
added: foo -> /home/eez/cvs/xyz/tfa/faq/zut/bar/foo |
| 334 |
/home/eez/cvs/xyz/tfa/faq/zut/bar/foo> <b>cd</b> |
| 335 |
/home/eez> <b>to foo</b> |
| 336 |
/home/eez/cvs/xyz/tfa/faq/zut/bar/foo></div> |
| 337 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 338 |
If one bookmarks a directory by its trailing component as happened in |
| 339 |
this case, it is not necessary to specify the mark. By default apparix |
| 340 |
will use the trailing component as the mark. So</p> |
| 341 |
<div class="verbatim">/home/eez/cvs/xyz/tfa/faq/zut/bar/foo> <b>bm</b> |
| 342 |
added: foo -> /home/eez/cvs/xyz/tfa/faq/zut/bar/foo</div> |
| 343 |
<p style="margin-top:0em; margin-bottom:0em">gives the same result.</p> |
| 344 |
<p style="margin-bottom:0" class="asd_par"> |
| 345 |
Another scenario is where you have some directory that contains a largish |
| 346 |
number of subdirectories, all of which you would like to have bookmarked. |
| 347 |
If the subdirectories have distinctive names this can be achieved in |
| 348 |
one fell swoop by marking the parent directory as a <i>portal</i>. This is |
| 349 |
similar to adding the parent directory to the CDPATH environment variable, |
| 350 |
except that apparix bookmarks are not part of the cd namespace. It is |
| 351 |
argued in <a class="intern" href="#notes">NOTES</a> that this is a good thing. |
| 352 |
Consider this:</p> |
| 353 |
<div class="verbatim">/home/cvs/bagger/boemel/mcl/mcl/src> <b>ls</b> |
| 354 |
alien/ CVS/ impala/ Makefile.am README shmcx/ |
| 355 |
attic/ giraffe/ lib/ Makefile.in shcl/ shmx/ |
| 356 |
contrib/ gmon.out Makefile mcl/ shmcl/ taurus/</div> |
| 357 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 358 |
Some of the subdirectories have not-so-distinct names such as <i>contrib</i> and |
| 359 |
<i>attic</i>, but they happen to be the directories least visited. |
| 360 |
Issuing:</p> |
| 361 |
<div class="verbatim">/home/cvs/bagger/boemel/mcl/mcl/src> <b>portal</b> |
| 362 |
[apparix] expanded 1 portal to 12 destinations</div> |
| 363 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 364 |
yields all of the subdirectories as destinations bookmarked by the last |
| 365 |
component of their path name. |
| 366 |
Incidentally, directory names such as <tt>CVS</tt> can be explicitly excluded |
| 367 |
from expansion by setting the environment variable <tt>APPARIXEXCLUDE</tt> |
| 368 |
appropriately — refer to section <a class="intern" href="#environment">ENVIRONMENT</a>. |
| 369 |
</p> |
| 370 |
<p style="margin-bottom:0" class="asd_par"> |
| 371 |
Bookmarks resulting from portal expansion are kept in a separate |
| 372 |
resource file (see <a class="intern" href="#files">FILES</a>). Portal expansions can be recreated |
| 373 |
by issuing</p> |
| 374 |
<div class="verbatim">apparix --rehash</div> |
| 375 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 376 |
This is useful to reflect a change in the directory naming structure |
| 377 |
underneath a portal.</p> |
| 378 |
|
| 379 |
<a name="dup"></a> |
| 380 |
<h2>duplicate resolution</h2> |
| 381 |
<p style="margin-bottom:0" class="asd_par"> |
| 382 |
Apparix allows identical bookmarks to point to different locations. |
| 383 |
When asked to visit such a bookmark it will by default |
| 384 |
present a list of options.</p> |
| 385 |
<p style="margin-bottom:0" class="asd_par"> |
| 386 |
The <a class="intern" href="#opt-favour"><b>-favour</b> <i><list></i></a> option can be used to automate |
| 387 |
resolution. <b><list></b> is a sequence of single characters, |
| 388 |
described further below. |
| 389 |
The order in which they are given denote the order in which |
| 390 |
resolution rules are applied. This option is typically used |
| 391 |
in the definition of the <b>to</b> function/alias or |
| 392 |
in the bash completion code.</p> |
| 393 |
<p style="margin-bottom:0" class="asd_par"> |
| 394 |
The <a class="intern" href="#opt-pick"><b>-pick</b> <i><num></i></a> option is used to resolve to a particular |
| 395 |
directory directly. This is useful when you already know where you want to |
| 396 |
go, and typically used for the <tt>now</tt> bookmark in conjunction with the bash |
| 397 |
<tt>whence</tt> function. Use <tt>whence now</tt> to see an indexed list of now |
| 398 |
bookmarks. It is possible to go to the desired directory by entering the |
| 399 |
bookmark index. It is possible to bypass the selection step by specifying |
| 400 |
<tt>whence now N</tt>. |
| 401 |
</p> |
| 402 |
<p style="margin-bottom:0" class="asd_par"> |
| 403 |
Duplicates are allowed because it can be useful to overwrite a bookmark with |
| 404 |
a new location. The old bookmark is kept as a matter of policy. Use |
| 405 |
<a class="intern" href="#opt-sm"><b>-sm</b></a> to explicitly squash duplicates. |
| 406 |
</p> |
| 407 |
<div class=" itemize " style="margin-top:1em; font-size:100%"> |
| 408 |
<div class=" item_compact"><div class=" item_leftalign nowrap " >l</div></div> |
| 409 |
<div class=" item_text " style="margin-left:2em"> |
| 410 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 411 |
<i>level</i>; prefer paths with fewer components.</p> |
| 412 |
</div> |
| 413 |
<div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_leftalign nowrap " >L</div></div> |
| 414 |
<div class=" item_text " style="margin-left:2em"> |
| 415 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 416 |
reverse of the above.</p> |
| 417 |
</div> |
| 418 |
<div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_leftalign nowrap " >o</div></div> |
| 419 |
<div class=" item_text " style="margin-left:2em"> |
| 420 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 421 |
<i>bookmark order</i>; prefer older entries. |
| 422 |
Entries appearing earlier in the file are considered older, |
| 423 |
but the actual date of creating the bookmark is not stored. |
| 424 |
Refer to <a class="intern" href="#edit">editing bookmarks</a> for more information.</p> |
| 425 |
</div> |
| 426 |
<div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_leftalign nowrap " >O</div></div> |
| 427 |
<div class=" item_text " style="margin-left:2em"> |
| 428 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 429 |
reverse of the above.</p> |
| 430 |
</div> |
| 431 |
<div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_leftalign nowrap " >r</div></div> |
| 432 |
<div class=" item_text " style="margin-left:2em"> |
| 433 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 434 |
<i>regular first</i>; prefer regular bookmarks over portal expansion.</p> |
| 435 |
</div> |
| 436 |
<div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_leftalign nowrap " >R</div></div> |
| 437 |
<div class=" item_text " style="margin-left:2em"> |
| 438 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 439 |
reverse of the above.</p> |
| 440 |
</div> |
| 441 |
</div> |
| 442 |
<p style="margin-bottom:0" class="asd_par"> |
| 443 |
If there are still ties after the specified rules have |
| 444 |
been applied apparix will simply take the first matching |
| 445 |
option. This behaviour cannot be further specified |
| 446 |
as the program uses a non-stable ordering routine.</p> |
| 447 |
<p style="margin-bottom:0" class="asd_par"> |
| 448 |
It is an absolute prerequisite that <a class="intern" href="#opt-favour"><b>-favour</b></a> is used in the bash |
| 449 |
completion code. Otherwise completion will fail (for a duplicated bookmark) |
| 450 |
while apparix is waiting for input. Refer to the tab completion description |
| 451 |
below.</p> |
| 452 |
|
| 453 |
<a name="sub"></a> |
| 454 |
<h2>subdirectory specification</h2> |
| 455 |
<p style="margin-bottom:0" class="asd_par"> |
| 456 |
When jumping (apparating) you can specify an additional subdirectory |
| 457 |
after the bookmark. Apparix will append the subdirectory to |
| 458 |
the destination.</p> |
| 459 |
<p style="margin-bottom:0" class="asd_par"> |
| 460 |
This is useful for projects with directory nodes corresponding |
| 461 |
with versions. Assume you have a directory structure such as this:</p> |
| 462 |
<div class="verbatim"> /x/y/z/OpusMagnum/v1/ |
| 463 |
/x/y/z/OpusMagnum/v2/ |
| 464 |
/x/y/z/OpusMagnum/v3/</div> |
| 465 |
<p style="margin-bottom:0" class="asd_par"> |
| 466 |
It is probably easiest to simply bookmark the OpusMagnum directory |
| 467 |
in some way (say with bookmark <tt>om</tt>). You can then issue |
| 468 |
<tt>to om v2</tt> to jump to <tt>OpusMagnum/v2</tt>. This is more flexible |
| 469 |
and maintainable than creating bookmarks <tt>om1</tt>, <tt>om2</tt>, <tt>om3</tt>. |
| 470 |
One could add OpusMagnum as a portal, but with generic names such |
| 471 |
as <tt>v1</tt> this is not a very extendible approach.</p> |
| 472 |
<p style="margin-bottom:0" class="asd_par"> |
| 473 |
See also the tab completion description below - it is possible |
| 474 |
to tab-complete on subdirectories of the apparix jump directory.</p> |
| 475 |
|
| 476 |
<a name="tab"></a> |
| 477 |
<h2>tab completion</h2> |
| 478 |
<p style="margin-bottom:0" class="asd_par"> |
| 479 |
The bash tab completion code does two things. First, it is possible to |
| 480 |
tab-complete on apparix bookmarks themselves, showing a listing of all |
| 481 |
available bookmarks (or iterating through them in cyclic mode, depending on |
| 482 |
your bash settings). Second, once a bookmark has been given tab completion |
| 483 |
will list or iterate over all the subdirectories of the directory associated |
| 484 |
with that bookmark. Specifying a string after the bookmark will limit |
| 485 |
tab-completion to directories matching the shell-pattern in string. |
| 486 |
<i>Very</i> useful.</p> |
| 487 |
<p style="margin-bottom:0" class="asd_par"> |
| 488 |
Be careful to not remove the <a class="intern" href="#opt-favour"><b>-favour</b> <i>list</i></a> option |
| 489 |
from the bash completion code. It is necessary to resolve |
| 490 |
duplicate bookmarks. |
| 491 |
</p> |
| 492 |
|
| 493 |
<a name="edit"></a> |
| 494 |
<h2>editing bookmarks</h2> |
| 495 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 496 |
Apparix appends new bookmarks to the end of the .apparixrc file. Nothing |
| 497 |
stops you from editing the file, and this is in fact recommended if for |
| 498 |
example you need to get rid of a bookmark and neither of <a class="intern" href="#opt-purge"><b>-purge</b></a>, |
| 499 |
<a class="intern" href="#opt-purge-mark"><b>-purge-mark</b></a>, <a class="intern" href="#opt-sd"><b>-sd</b></a>, |
| 500 |
<a class="intern" href="#opt-sm"><b>-sm</b></a> fulfills your needs. It was an easy design choice |
| 501 |
not to equip apparix with editor capabilities.</p> |
| 502 |
|
| 503 |
<a name="mov"></a> |
| 504 |
<h2>copying and moving files</h2> |
| 505 |
<p style="margin-bottom:0" class="asd_par"> |
| 506 |
It is straightforward to copy or move files to locations known |
| 507 |
by apparix. Examples:</p> |
| 508 |
<div class="verbatim">BASH and variants |
| 509 |
cp FOO $(apparix zoem) |
| 510 |
mv BAR $(apparix zoem doc) |
| 511 |
mv BAR $(apparix zoem doc)/test |
| 512 |
|
| 513 |
CSH and variants |
| 514 |
cp FOO `apparix zoem` |
| 515 |
mv BAR `apparix zoem doc`/test</div> |
| 516 |
|
| 517 |
<a name="list"></a> |
| 518 |
<h2>listing bookmarks</h2> |
| 519 |
<p style="margin-bottom:0" class="asd_par"> |
| 520 |
Simply issuing apparix gives you a list of bookmarks grouped into three |
| 521 |
categories, portals, expansions, and bookmarks. Use the <a class="intern" href="#opt-d"><b>-d</b></a> option |
| 522 |
to dump the resource file to STDOUT exactly as it is. This can be useful |
| 523 |
when you intend to use the <a class="intern" href="#opt-u"><b>-u</b> <i>num</i></a> option to remove bookmarks or |
| 524 |
portals that were most recently added.</p> |
| 525 |
<p style="margin-bottom:0" class="asd_par"> |
| 526 |
Use <a class="intern" href="#opt-l"><b>-l</b></a> to list all available jumps without their destinations. |
| 527 |
The jumps are grouped into expansions resulting from portals and |
| 528 |
regular bookmarks.</p> |
| 529 |
|
| 530 |
<a name="cd"></a> |
| 531 |
<h2>replacing cd</h2> |
| 532 |
<p style="margin-bottom:0" class="asd_par"> |
| 533 |
With the supplied definition(s) of <b>to</b>, apparix will first see whether |
| 534 |
the mark is the name of a directory, accessible from the current directory. |
| 535 |
A directory is accessible if it would be a valid argument to cd, so it need |
| 536 |
not necessarily be a subdirectory of the current directory. If the mark is |
| 537 |
not an accessible directory, apparix will then try to do a lookup of the |
| 538 |
mark in the bookmark files. This behaviour can be inverted to do the lookup |
| 539 |
first and the current directory thereafter. Both modes can be used to make |
| 540 |
<b>to</b> a drop-in replacement for <i>cd</i>. Additionally and again similar |
| 541 |
to <i>cd</i>, <tt>'to -'</tt> will take you to the previous directory, and |
| 542 |
specifying <tt>to</tt> without arguments will take you to your home directory. |
| 543 |
</p> |
| 544 |
<p style="margin-bottom:0" class="asd_par"> |
| 545 |
The bash completion code acts accordingly, and should transparently |
| 546 |
complete on both marks and directories. |
| 547 |
</p> |
| 548 |
|
| 549 |
<a name="options"></a> |
| 550 |
<h2>OPTIONS</h2> |
| 551 |
<p style="margin-bottom:0" class="asd_par"> |
| 552 |
For bookmarking and jumping apparix is best invoked by using the aliases |
| 553 |
(tcsh-variants) or functions (sh/bash) listed in <a class="intern" href="#files">FILES</a>. |
| 554 |
Apparix has a few options that are useful for pruning, squashing and |
| 555 |
rehasing bookmarks. These are best issued by invoking apparix directly.</p> |
| 556 |
<p style="margin-bottom:0" class="asd_par"> |
| 557 |
If you are interested in marks or destinations matching a certain pattern, |
| 558 |
simply issue apparix without arguments and pipe it through |
| 559 |
your program of choice.</p> |
| 560 |
<p style="margin-bottom:0" class="asd_par"> |
| 561 |
Unary options (those without arguments) usually start with two hyphens |
| 562 |
except for standardized options such as <a class="intern" href="#opt-h"><b>-h</b></a>. |
| 563 |
Options that take an argument can be converted to a unary key=value notation, |
| 564 |
e.g. <b>-purge-mark</b> <b>foo</b> is equivalent to <b>--purge-mark</b>=<b>foo</b>.</p> |
| 565 |
<p style="margin-bottom:0" class="asd_par"> |
| 566 |
When invoked without arguments apparix will simply dump its bookmarks.</p> |
| 567 |
<div class=" itemize " style="margin-top:1em; font-size:100%"> |
| 568 |
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--add-mark"></a><b>--add-mark</b> (<i>add jump bookmark</i>)</div></div> |
| 569 |
<div class=" item_text " style="margin-left:2em"> |
| 570 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 571 |
This options expects trailing <i>[mark [destination]]</i> argument(s). |
| 572 |
Both arguments are optional. If a single argument is given it |
| 573 |
is interpreted as a bookmark name to be mapped to the current directory. |
| 574 |
If two arguments are given the last argument is taken as the |
| 575 |
target directory. If no argument is given apparix will enlist |
| 576 |
the current directory as a target bookmarked by the trailing component |
| 577 |
of the directory path.</p> |
| 578 |
</div> |
| 579 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--add-portal"></a><b>--add-portal</b> (<i>add portal bookmark</i>)</div></div> |
| 580 |
<div class=" item_text " style="margin-left:2em"> |
| 581 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 582 |
This option enlists a directory as a portal and adds all subdirectories |
| 583 |
as bookmarks. The name of the bookmark is simply the name of the |
| 584 |
subdirectory. By default the current directory is added as a portal. |
| 585 |
An optional trailing argument will override this behaviour and |
| 586 |
instead be interpreted as the portal location.</p> |
| 587 |
</div> |
| 588 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--try-current-first"></a><b>--try-current-first</b> (<i>try current directory before lookup</i>)</div></div> |
| 589 |
<div class=" item_text " style="margin-left:2em"> |
| 590 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 591 |
This option is useful in the definition of the <b>to</b> wrapper. Before |
| 592 |
attempting any lookup of the mark, apparix tests whether the supplied mark |
| 593 |
exists as a subdirectory in the current directory. If it does, |
| 594 |
the mark is simply expanded to itself. |
| 595 |
</p> |
| 596 |
</div> |
| 597 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--try-current-last"></a><b>--try-current-last</b> (<i>try current directory if lookup fails</i>)</div></div> |
| 598 |
<div class=" item_text " style="margin-left:2em"> |
| 599 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 600 |
This option is useful in the definition of the <b>to</b> wrapper. If |
| 601 |
lookup of the mark fails, apparix tests whether the supplied mark |
| 602 |
exists as a subdirectory in the current directory. If it does, |
| 603 |
the mark is simply expanded to itself. |
| 604 |
</p> |
| 605 |
</div> |
| 606 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--notify-current"></a><b>--notify-current</b> (<i>notify if current directory is used</i>)</div></div> |
| 607 |
<div class=" item_text " style="margin-left:2em"> |
| 608 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 609 |
This option is useful in the definition of the <i>bf</i> wrapper |
| 610 |
in conjunction with either <b>--try-current-first</b> |
| 611 |
or <b>--try-current-last</b>. |
| 612 |
If the mark is found as a subdirectory in the current directory, |
| 613 |
apparix notifies the user of this fact (on the diagnostic stream). |
| 614 |
</p> |
| 615 |
</div> |
| 616 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-sm"></a><b>-sm</b> <mar> (<i>squash repeated marks</i>)</div></div> |
| 617 |
<div class=" item_text " style="margin-left:2em"> |
| 618 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 619 |
Apparix will squash bookmarks with mark <tt><mark></tt>. |
| 620 |
This is useful when a mark points to a versioned project, and the |
| 621 |
project is updated to a new version and a new directory.</p> |
| 622 |
<p style="margin-bottom:0" class="asd_par"> |
| 623 |
Apparix will by default keep the last one occurring in the resource |
| 624 |
file (corresponding with <b>-favour</b> <b>O</b>). This option respects the |
| 625 |
<a class="intern" href="#opt-favour"><b>-favour</b></a> option if given. Duplicating an already existing mark |
| 626 |
can be useful when it identifies a project for which the underlying |
| 627 |
directory changes every once in a while (e.g. the project is downloaded from |
| 628 |
external sources and comes with version information). It is not strictly |
| 629 |
necessary to squash bookmarks since <b>to</b> functions/macros that are |
| 630 |
equipped with the <a class="intern" href="#opt-favour"><b>-favour</b></a> option will generally resolve |
| 631 |
duplicate matches. |
| 632 |
</p> |
| 633 |
</div> |
| 634 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-sd"></a><b>-sd</b> <mark> (<i>squash repeated destinations</i>)</div></div> |
| 635 |
<div class=" item_text " style="margin-left:2em"> |
| 636 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 637 |
All other bookmarks with the same destination as <tt><mark></tt> are removed. |
| 638 |
This is useful when a given destination has acquired multiple |
| 639 |
bookmarks and you decide to settle on a favourite. |
| 640 |
</p> |
| 641 |
</div> |
| 642 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-lm"></a><b>-lm</b> <mark> (<i>list bookmarks with this mark</i>)</div></div> |
| 643 |
<div class=" item_text " style="margin-left:2em"> |
| 644 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 645 |
It lists all bookmarks <tt><mark></tt> (noting that it may point to |
| 646 |
multiple locations). |
| 647 |
</p> |
| 648 |
</div> |
| 649 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-ld"></a><b>-ld</b> <mark> (<i>list repeated destinations</i>)</div></div> |
| 650 |
<div class=" item_text " style="margin-left:2em"> |
| 651 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 652 |
This lists all bookmarks <tt><mark></tt> (noting that it may point to |
| 653 |
multiple locations) and additionally lists all other bookmarks that share |
| 654 |
the destination with any of the first bookmarks. This allows one to predict |
| 655 |
the effect of issuing <tt>apparix -sd <mark></tt>. |
| 656 |
</p> |
| 657 |
</div> |
| 658 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-purge"></a><b>-purge</b> pat (<i>delete bookmarks</i>)</div></div> |
| 659 |
<div class=" item_text " style="margin-left:2em"> |
| 660 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 661 |
This deletes bookmarks where destination matches <i>pat</i>. |
| 662 |
All deleted bookmarks are printed to STDOUT. Thus if you regret |
| 663 |
deleting a bookmark it is easy to add it back. Portal specifications |
| 664 |
are never affected.</p> |
| 665 |
</div> |
| 666 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-purge-mark"></a><b>-purge-mark</b> (<i>pat</i>)</div></div> |
| 667 |
<div class=" item_text " style="margin-left:2em"> |
| 668 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 669 |
This deletes bookmarks where mark matches <i>pat</i>. |
| 670 |
Portal specifications are never affected.</p> |
| 671 |
</div> |
| 672 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-d"></a><b>-d</b> (<i>dump resource file to STDOUT</i>)</div></div> |
| 673 |
<div class=" item_text " style="margin-left:2em"> |
| 674 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 675 |
Dump resource file to STDOUT.</p> |
| 676 |
</div> |
| 677 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-l"></a><b>-l</b> (<i>list available jumps</i>)</div></div> |
| 678 |
<div class=" item_text " style="margin-left:2em"> |
| 679 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 680 |
List available jumps paragraph-style. Portal specifications themselves |
| 681 |
are excluded, and regular jumps and jumps resulting from portal expansions |
| 682 |
are listed under different headers.</p> |
| 683 |
</div> |
| 684 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-u"></a><b>-u</b> <num> (<i>remove last <num> additions</i>)</div></div> |
| 685 |
<div class=" item_text " style="margin-left:2em"> |
| 686 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 687 |
Remove last <num> additions. Portal specifications and regular |
| 688 |
jumps are treated alike.</p> |
| 689 |
</div> |
| 690 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--rehash"></a><b>--rehash</b> (<i>re-expand portal bookmarks</i>)</div></div> |
| 691 |
<div class=" item_text " style="margin-left:2em"> |
| 692 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 693 |
Apparix will reread the resource file and reexpand portal |
| 694 |
locations. Useful if directories have been added, renamed, |
| 695 |
or removed. Refer to section <a class="intern" href="#environment">ENVIRONMENT</a> for the effect |
| 696 |
that the environment variable <tt>APPARIXEXCLUDE</tt> has on portal expansion.</p> |
| 697 |
</div> |
| 698 |
<div style="margin-top:0em"> </div><div class=" item_cascade item_leftalign nowrap" ><a name="opt-favour"></a><b>-favour</b> <list> (<i>set duplicate resolution policy</i>)</div><div class=" item_cascade item_leftalign nowrap" ><a name="opt-pick"></a><b>-pick</b> <num> (<i>immediate duplicate resolution</i>)</div> |
| 699 |
<div class=" item_text " style="margin-left:2em"> |
| 700 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 701 |
These options have a section to themselves. Refer to <a class="intern" href="#dup">duplicate resolution</a>.</p> |
| 702 |
</div> |
| 703 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--cwd"></a><b>--cwd</b> (<i>use getcwd(3), not pwd(1)</i>)</div></div> |
| 704 |
<div class=" item_text " style="margin-left:2em"> |
| 705 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 706 |
By default aparix uses the program <i>pwd</i>(1) rather than |
| 707 |
the system call <i>getcwd</i>(3). On some systems it was found |
| 708 |
that the latter results in paths that contain machine-specific |
| 709 |
mount components. |
| 710 |
Appparix will use <i>getcwd</i>(3) when <a class="intern" href="#opt--cwd"><b>--cwd</b></a> is used.</p> |
| 711 |
</div> |
| 712 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--shell-examples"></a><b>--shell-examples</b> (<i>output example macros</i>)</div></div> |
| 713 |
<div class=" item_text " style="margin-left:2em"> |
| 714 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 715 |
This outputs example macros. They are also listed in the |
| 716 |
<a class="intern" href="#files">FILES</a> section though.</p> |
| 717 |
</div> |
| 718 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--bu"></a><b>--bu</b> (<i>create backup of the resource file</i>)</div></div> |
| 719 |
<div class=" item_text " style="margin-left:2em"> |
| 720 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 721 |
This creates the backup file in .apparixrc.bu.</p> |
| 722 |
</div> |
| 723 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-bu"></a><b>-bu</b> fname (<i>create backup of the resource file</i>)</div></div> |
| 724 |
<div class=" item_text " style="margin-left:2em"> |
| 725 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 726 |
This creates the backup file in <i>fname</i>. Use |
| 727 |
<a class="intern" href="#opt-d"><b>-d</b></a> or <b>-bu</b> <b>-</b> to dump to STDOUT.</p> |
| 728 |
</div> |
| 729 |
<div style="margin-top:0em"> </div><div class=" item_cascade item_leftalign nowrap" ><a name="opt-h"></a><b>-h</b> (<i>show synopsis</i>)</div><div class=" item_cascade item_leftalign nowrap" ><a name="opt--apropos"></a><b>--apropos</b> (<i>show synopsis</i>)</div> |
| 730 |
<div class=" item_text " style="margin-left:2em"> |
| 731 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 732 |
print synopsis of all options</p> |
| 733 |
</div> |
| 734 |
</div> |
| 735 |
|
| 736 |
<a name="environment"></a> |
| 737 |
<h2>ENVIRONMENT</h2> |
| 738 |
<div class=" itemize " style="margin-top:1em; font-size:100%"> |
| 739 |
<div class=" item_cascade"><div class=" item_leftalign nowrap " >APPARIXEXCLUDE</div></div> |
| 740 |
<div class=" item_text " style="margin-left:2em"> |
| 741 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 742 |
This variable specifies exclusion behaviour |
| 743 |
when portals are expanded with the <tt>--rehash</tt> option. |
| 744 |
It has the following syntax: |
| 745 |
</p> |
| 746 |
<div class="verbatim"> <[:,][<string>]>+</div> |
| 747 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 748 |
That is, a list of names with each name preceded by a colon or a comma. |
| 749 |
A colon indicates that <tt><string></tt> triggers exclusion of directory names |
| 750 |
for which the trailing component is identical to <tt><string></tt>. |
| 751 |
A comma indicates that <tt><string></tt> triggers exclusion of directory names |
| 752 |
for which the trailing component contains <tt><string></tt> as a substring. |
| 753 |
Consider: |
| 754 |
</p> |
| 755 |
<div class="verbatim"> export APPARIXEXCLUDE=:CVS:lib,tmp # A - example |
| 756 |
export APPARIXEXCLUDE=, # B - curiosity</div> |
| 757 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 758 |
The first excludes directory names <tt>CVS</tt> and <tt>lib</tt> and any directory |
| 759 |
name having <tt>tmp</tt> as a substring. |
| 760 |
The second example will effectively disable portals, |
| 761 |
as it speficies the empty string which is a substring of all strings. |
| 762 |
</p> |
| 763 |
</div> |
| 764 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " >APPARIXTAG</div></div> |
| 765 |
<div class=" item_text " style="margin-left:2em"> |
| 766 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 767 |
This variable, if set, is incorporated into the names of the |
| 768 |
apparix resource files. By default these are <tt>.apparixrc</tt> and <tt>.apparixexpand</tt>. |
| 769 |
When APPARIXTAG is set to <tt><tag></tt> they become <tt>.<tag>apparixrc</tt> and |
| 770 |
<tt>.<tag>apparixexpand</tt>. |
| 771 |
This can be used e.g. to maintain different sets of bookmarks on different |
| 772 |
host machines. |
| 773 |
</p> |
| 774 |
</div> |
| 775 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " >APPARIXLOG</div></div> |
| 776 |
<div class=" item_text " style="margin-left:2em"> |
| 777 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 778 |
This variable, if set, is interpreted as the name of a log file. |
| 779 |
The log file keeps track of all newly added bookmarks and |
| 780 |
portals without ever deleting anything, in the same format |
| 781 |
as the <tt>.apparixrc</tt> file. If this variable is not set |
| 782 |
nothing is tracked. |
| 783 |
</p> |
| 784 |
</div> |
| 785 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " >APPARIXPURGE</div></div> |
| 786 |
<div class=" item_text " style="margin-left:2em"> |
| 787 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 788 |
This changes the way apparix dumps purged bookmarks to STDOUT. |
| 789 |
By default they are dumped as command lines that will reimport |
| 790 |
the bookmarks if issued (i.e. cut and pasted). |
| 791 |
By setting this variable to 1 purged bookmarks are dumped |
| 792 |
in the format used in the <tt>.apparixrc</tt> file. |
| 793 |
</p> |
| 794 |
</div> |
| 795 |
</div> |
| 796 |
|
| 797 |
<a name="files"></a> |
| 798 |
<h2>FILES</h2> |
| 799 |
<p style="margin-bottom:0" class="asd_par"> |
| 800 |
You should use aliases or functions to make apparix really useful. |
| 801 |
Get them from apparix by giving it the --shell-examples option, |
| 802 |
or from further below. |
| 803 |
Note the fragment that provides <b>to</b> argument completion in bash. |
| 804 |
</p> |
| 805 |
<div class=" itemize " style="margin-top:1em; font-size:100%"> |
| 806 |
<div class=" item_cascade"><div class=" item_leftalign nowrap " >$HOME/.apparixrc</div></div> |
| 807 |
<div class=" item_text " style="margin-left:2em"> |
| 808 |
<p style="margin-top:0em; margin-bottom:0em">This is the primary resource file. There is usually no |
| 809 |
need to edit it by hand. Sometimes it can be useful to edit |
| 810 |
by hand to remove an unwanted bookmark; refer to <a class="intern" href="#edit">editing bookmarks</a>.</p> |
| 811 |
</div> |
| 812 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " >$HOME/.apparixrc.bu</div></div> |
| 813 |
<div class=" item_text " style="margin-left:2em"> |
| 814 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 815 |
Apparix creates a back-up file whenever it is asked to |
| 816 |
remove entries from it. Refer |
| 817 |
to <a class="intern" href="#edit">editing bookmarks</a> for options inducing removal. |
| 818 |
You can explicitly require a backup to be made by |
| 819 |
either of <a class="intern" href="#opt--bu"><b>--bu</b></a> or <a class="intern" href="#opt-bu"><b>-bu</b> <i>fname</i></a>.</p> |
| 820 |
</div> |
| 821 |
<div style="margin-top:0em"> </div><div class=" item_cascade"><div class=" item_leftalign nowrap " >$HOME/.apparixexpand</div></div> |
| 822 |
<div class=" item_text " style="margin-left:2em"> |
| 823 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 824 |
This contains bookmarks that are expanded from portals. |
| 825 |
A portal is simply some directory. The names of all subdirectories |
| 826 |
are taken as bookmarks that point to those subdirectories. |
| 827 |
This file can be recreated by issuing</p> |
| 828 |
<div class="verbatim">apparix --rehash</div> |
| 829 |
</div> |
| 830 |
<div style="margin-top:0em"> </div><div class=" item_cascade item_leftalign nowrap" >$HOME/.bashrc</div><div class=" item_cascade item_leftalign nowrap" >$HOME/.tcshrc</div><div class=" item_cascade item_leftalign nowrap" >$HOME/.cshrc</div> |
| 831 |
<div class=" item_text " style="margin-left:2em"> |
| 832 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 833 |
Add the code you need to the appropriate rc file. The macros and functions |
| 834 |
below point <i>cd</i>(1) in the right direction.</p> |
| 835 |
</div> |
| 836 |
</div> |
| 837 |
<div class="verbatim">BASH-style functions |
| 838 |
--- |
| 839 |
function to () { |
| 840 |
if test "$2"; then |
| 841 |
cd "$(apparix --try-current-first -favour rOl "$1" "$2" || echo .)" |
| 842 |
elif test "$1"; then |
| 843 |
if test "$1" == '-'; then |
| 844 |
cd - |
| 845 |
else |
| 846 |
cd "$(apparix --try-current-first -favour rOl "$1" || echo .)" |
| 847 |
fi |
| 848 |
else |
| 849 |
cd $HOME |
| 850 |
fi |
| 851 |
} |
| 852 |
function bm () { |
| 853 |
if test "$2"; then |
| 854 |
apparix --add-mark "$1" "$2"; |
| 855 |
elif test "$1"; then |
| 856 |
apparix --add-mark "$1"; |
| 857 |
else |
| 858 |
apparix --add-mark; |
| 859 |
fi |
| 860 |
} |
| 861 |
function portal () { |
| 862 |
if test "$1"; then |
| 863 |
apparix --add-portal "$1"; |
| 864 |
else |
| 865 |
apparix --add-portal; |
| 866 |
fi |
| 867 |
} |
| 868 |
# function to generate list of completions from .apparixrc |
| 869 |
function _apparix_aliases () |
| 870 |
{ cur=$2 |
| 871 |
dir=$3 |
| 872 |
COMPREPLY=() |
| 873 |
nullglobsa=$(shopt -p nullglob) |
| 874 |
shopt -s nullglob |
| 875 |
if let $(($COMP_CWORD == 1)); then |
| 876 |
# now cur=<apparix mark> (completing on this) and dir='to' |
| 877 |
# Below will not complete on subdirectories. swap if so desired. |
| 878 |
# COMPREPLY=( $( cat $HOME/.apparix{rc,expand} | grep "j,.*$cur.*," | cut -f2 -d, ) ) |
| 879 |
COMPREPLY=( $( (cat $HOME/.apparix{rc,expand} | grep "\<j," | cut -f2 -d, ; ls -1p | grep '/$' | tr -d /) | grep "\<$cur.*" ) ) |
| 880 |
else |
| 881 |
# now dir=<apparix mark> and cur=<subdirectory-of-mark> (completing on this) |
| 882 |
dir=`apparix --try-current-first -favour rOl $dir 2>/dev/null` || return 0 |
| 883 |
eval_compreply="COMPREPLY=( $( |
| 884 |
cd "$dir" |
| 885 |
\ls -d $cur* | while read r |
| 886 |
do |
| 887 |
[[ -d "$r" ]] && |
| 888 |
[[ $r == *$cur* ]] && |
| 889 |
echo \"${r// /\\ }\" |
| 890 |
done |
| 891 |
) )" |
| 892 |
eval $eval_compreply |
| 893 |
fi |
| 894 |
$nullglobsa |
| 895 |
return 0 |
| 896 |
} |
| 897 |
# command to register the above to expand when the 'to' command's args are |
| 898 |
# being expanded |
| 899 |
complete -F _apparix_aliases to |
| 900 |
--- |
| 901 |
CSH-style aliases |
| 902 |
--- |
| 903 |
# The outcommented alias does not supplant cd, the other one does. |
| 904 |
# alias to 'cd `(apparix -favour rOl \!* || echo -n .)`' |
| 905 |
alias to '(test "x-" = "x\!*") && cd - || (test "x" != "x\!*") && cd `(apparix --try-current-first -favour rOl \!* || echo -n .)` || cd' |
| 906 |
alias bm 'apparix --add-mark \!*' |
| 907 |
alias portal 'apparix --add-portal \!*' |
| 908 |
---</div> |
| 909 |
<p style="margin-bottom:0" class="asd_par">More elaborate setups are possible. This CSH-style alias:</p> |
| 910 |
<div class="verbatim">alias to '(test "x" != "x\!*") && cd `(apparix -favour rOl \!* || echo -n .)` || apparix -l'</div> |
| 911 |
<p style="margin-bottom:0" class="asd_par">lists all available jumps if invoked without arguments.</p> |
| 912 |
|
| 913 |
<a name="notes"></a> |
| 914 |
<h2>NOTES</h2> |
| 915 |
<p style="margin-bottom:0" class="asd_par"> |
| 916 |
Below follow some comments on other approaches to file system navigation. |
| 917 |
<a class="intern" href="#history">HISTORY</a> explains the difference between the venerable <b>cdargs</b> |
| 918 |
program and <b>apparix</b>. |
| 919 |
</p> |
| 920 |
<p style="margin-bottom:0" class="asd_par"> |
| 921 |
CDPATH is only useful in cases where a given directory has subdirectories |
| 922 |
with distinctive names. It does not usually scale well when there are |
| 923 |
more than a few paths in CDPATH. |
| 924 |
</p> |
| 925 |
<p style="margin-bottom:0" class="asd_par"> |
| 926 |
Some people use aliases to jump to often visited directories. |
| 927 |
I was one of them for a period of ten years. The fact is, |
| 928 |
those aliases are cumbersome to create and remove and they |
| 929 |
clutter up the alias namespace. They can clash with |
| 930 |
executable names when the alias includes the <i>cd</i> part. This sometimes |
| 931 |
prohibits one from assigning the logical bookmark to a given |
| 932 |
location, especially when one has a lot of source code locations. |
| 933 |
They can clash with directory names when |
| 934 |
the aliases just expand to the location. This again means that |
| 935 |
sometimes a location cannot be assigned its logical bookmark. |
| 936 |
I have found that setting <i>cd</i> jumps aside in their own namespace |
| 937 |
improves file system navigation by a large factor. |
| 938 |
</p> |
| 939 |
<p style="margin-bottom:0" class="asd_par"> |
| 940 |
It is also possible to create symlinks to often |
| 941 |
visited files. Again, creation and removal of these are cumbersome. |
| 942 |
One could of course create shell functions with a similar interface |
| 943 |
to apparix or cdargs to handle the symlink lifecycle. |
| 944 |
On Linux Weekly News <i>nix</i> suggested to put these symlinks |
| 945 |
in a single directory and add that directory to CDPATH. |
| 946 |
This is quite a neat trick and effectively creates a bookmark |
| 947 |
navigation system. |
| 948 |
</p> |
| 949 |
<p style="margin-bottom:0" class="asd_par"> |
| 950 |
Still there are problems with the above approach. |
| 951 |
One problem with the symlink approach is that they are a bit |
| 952 |
awkward to edit. One could make a utility to wrap around the problem, |
| 953 |
but in the end the directory-with-symlinks would |
| 954 |
functionally be the same as apparix's <b>.apparixrc</b> resource file, |
| 955 |
only more of a kludge. |
| 956 |
Another problem is that symlinks are awkard when traversing |
| 957 |
the file system. They confuse the notion of parent directory |
| 958 |
and '<tt>cd ..</tt>' mostly does the unexpected. Sometimes '<tt>..</tt>' |
| 959 |
has a different meaning to <b>cd</b> than it has to another application, |
| 960 |
as one will trace back symlinks and the other will not. |
| 961 |
Finally, a minor objection |
| 962 |
is that I find it convenient to have bookmarks in a separate |
| 963 |
namespace than that of <i>cd</i>(1). Jumps are magical and it is |
| 964 |
natural to invoke them by a different method. This is in fact |
| 965 |
how apparix acquired its CDPATH behaviour. I used CDPATH to |
| 966 |
jump to a few particular source directories with distinct names |
| 967 |
that lay deeply hidden in some CVS directory. Once I started using |
| 968 |
apparix however, I would mistakenly issue <i>to</i> rather than <i>cd</i> |
| 969 |
to jump to those locations. My brain classified both types of jump |
| 970 |
in the same category. |
| 971 |
</p> |
| 972 |
<p style="margin-bottom:0" class="asd_par"> |
| 973 |
Apparix (and cdargs) have another use besides jumping, namely |
| 974 |
annotation. Whenever I end up in an esoteric part of the file system and |
| 975 |
need to make a quick note of the location, I simply bookmark it. |
| 976 |
</p> |
| 977 |
<p style="margin-bottom:0" class="asd_par"> |
| 978 |
On SlashDot, that eternal source of wisdom or alternatively |
| 979 |
the geek wheel of suffering, Clueless Moron offered the following gems.</p> |
| 980 |
<div class="verbatim"> mk() { eval ${1:-MKPWD}=\"`pwd`\"; } |
| 981 |
rt() { eval cd \"\$${1:-MKPWD}\";pwd; } |
| 982 |
|
| 983 |
# type "mk" (as in "mark") and "rt" (as in "return") to mark |
| 984 |
# a directory and later go back to it. |
| 985 |
# Or give it a name: do "mk foo", and later on "rt foo"</div> |
| 986 |
<p style="margin-bottom:0" class="asd_par"> |
| 987 |
This of course is a per-session mechanism, but noteworthy |
| 988 |
for its simplicity. I am not sure whether csh-style shells |
| 989 |
could offer an equivalent.</p> |
| 990 |
<p style="margin-bottom:0" class="asd_par"> |
| 991 |
A feature shared by apparix and cdargs is that adding a bookmark |
| 992 |
immediately takes effect in all shells. There is no need to |
| •993 |
source some resource file, as the applications do this every time |
| 994 |
they are invoked. It is fast, do not worry. |
| 995 |
</p> |
| 996 |
|
| 997 |
<a name="bugs"></a> |
| 998 |
<h2>BUGS</h2> |
| 999 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 1000 |
The resource file parsing code thinks that parentheses are special. |
| 1001 |
Also records are currently separated by commas. Accordingly, apparix will |
| 1002 |
hitch if a path name contains a parenthesis or a comma.</p> |
| 1003 |
|
| 1004 |
<a name="author"></a> |
| 1005 |
<h2>AUTHOR</h2> |
| 1006 |
<p style="margin-top:0em; margin-bottom:0em"> |
| 1007 |
Stijn van Dongen.</p> |
| 1008 |
|
| 1009 |
<a name="thanks"></a> |
| 1010 |
<h2>THANKS</h2> |
| 1011 |
<p style="margin-bottom:0" class="asd_par"> |
| 1012 |
Stefan Kamphausen wrote <b>cdargs</b>, the inspiration for apparix.</p> |
| 1013 |
<p style="margin-bottom:0" class="asd_par"> |
| 1014 |
Sitaram Chamarty fixed up some of the existing bash code, and added the tab |
| 1015 |
completion part (basing this on similar code in cdargs). He does not |
| 1016 |
garantuee predictable or even pretty results if there are spaces in the |
| 1017 |
directory names which you attempt to complete. <a class="intern" href="#author">AUTHOR</a> would like |
| 1018 |
to submit that spaces in path names are evil, and that the completion code |
| 1019 |
seems to work in their evil presence anyway. Just <a class="intern" href="#bugs">don't put |
| 1020 |
commas</a> in path names. |
| 1021 |
</p> |
| 1022 |
<p style="margin-bottom:0" class="asd_par"> |
| 1023 |
The autotooled build environment was modified from a template written |
| 1024 |
by Joost van Baal. |
| 1025 |
</p> |
| 1026 |
<p style="margin-bottom:0" class="asd_par"> |
| 1027 |
Several people suggested to enable apparix to merge accessible directories |
| 1028 |
and marks, but Matias Piipari phrased it the most convincingly. |
| 1029 |
</p> |
| 1030 |
|
| 1031 |
<a name="history"></a> |
| 1032 |
<h2>HISTORY</h2> |
| 1033 |
<p style="margin-bottom:0" class="asd_par"> |
| 1034 |
Apparix was created to optimize a scenario that |
| 1035 |
<a target="_parent" class="extern" href="http://www.skamphausen.de/cgi-bin/ska/CDargs">cdargs</a> does not support |
| 1036 |
very well, namely where the mark (called <i>needle</i> in cdargs) is always |
| 1037 |
known. As additional features apparix supports CDPATH-style behaviour, |
| 1038 |
derived subdirectory specification, and transparent treatment of bookmarks |
| 1039 |
and directories, all integrated with bash tab completion. In other respects |
| 1040 |
apparix is a much simpler application. <b>cdargs</b> offers menu-based |
| 1041 |
navigation of the file system and the bookmark list, which apparix does not. |
| 1042 |
</p> |
| 1043 |
</body> |
| 1044 |
</html> |