Skip to content

Commit

Permalink
update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@wting
wting committed Jan 8, 2014
1 parent 35bc63c commit f5d13da
Show file tree
Hide file tree
Showing 9 changed files with 182 additions and 534 deletions.
2 changes: 1 addition & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ uninstall:

docs:
pandoc -s -w man docs/manpage_header.md docs/header.md docs/body.md -o docs/autojump.1
pandoc -s -w markdown docs/header.md docs/install.md docs/development.md docs/body.md -o README.md
pandoc -s -w markdown docs/header.md docs/install.md docs/body.md -o README.md

lint:
@flake8 ./ --config=setup.cfg
Expand Down
257 changes: 63 additions & 194 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,137 +3,46 @@ NAME

autojump - a faster way to navigate your filesystem

SYNOPSIS
--------

Jump to a previously visited directory that contains 'foo':

j foo

Jump to a previously visited subdirectory of the current directory:

jc bar

Show database entries and their respective key weights:

j --stat

DESCRIPTION
-----------

autojump is a faster way to navigate your filesystem. It works by
maintaining a database of the directories you use the most from the
command line. Directories must be visited first before they can be
jumped to.

INSTALLATION
------------

### REQUIREMENTS

- Python v2.6+
- Bash v4.0 for tab completion (or zsh)

If you are unable to update Python to a supported version, older
versions of autojump can be [downloaded][dl] and installed manually.

- Python v2.4 is supported by [release v12][v12].

### AUTOMATIC INSTALLATION

**Linux**

autojump is included in the following distro repositories, please use
relevant package management utilities to install (e.g. yum, apt-get,
etc):

- Debian\* testing/unstable, Ubuntu, Linux Mint
- RedHat, Fedora, CentOS
- ArchLinux
- Gentoo
- Frugalware
- Slackware
command line.

\* Requires manual activation for policy reasons, please see
`/usr/share/doc/autojump/README.Debian`.
*Directories must be visited first before they can be jumped to.*

**Mac**

Homebrew is the recommended installation method for Mac OS X:

brew install autojump

MacPorts also available:

port install autojump

**Other**

Please check the [Wiki][wiki] for an up to date listing of installation methods.

### MANUAL INSTALLATION

Grab a copy of autojump:

git clone git://github.com/joelthelion/autojump.git

Run the installation script:

cd autojump
./install.sh [ --local ]

and follow on screen instructions.

### MANUAL UNINSTALLATION

It is recommended to use your distribution's relevant package management
utilities, unless you installed manually or ran into uninstallation
issues.

Grab a copy of autojump:

git clone git://github.com/joelthelion/autojump.git

Run the uninstallation script:

cd autojump
./uninstall.sh

and follow on screen instructions.

If you keep getting `autojump: command not found` at the prompt,
do:`unset PROMPT_COMMAND`. You can also restart your shell.

DEVELOPMENT
-----------
USAGE
-----

The source code is primarily in `./bin/autojump`. Various shell wrapper
scripts are also available in `./bin/`.
`j` is a convenience wrapper function around `autojump`. Any option that
can be used with `autojump` can be used with `j` and vice versa.

Documentation is in various files under `./docs/`. Build documentation
with the command:
- Jump To A Directory That Contains `foo`:

make docs
j foo

OPTIONS
-------
- Jump To A Child Directory

Options must be passed to 'autojump' and not the 'j' wrapper function.
Sometimes it's convenient to jump to a child directory
(sub-directory of current directory) rather than typing out the full
name.

-i, --increase manually increase current directory weight
jc bar

-d, --decrease manually decrease current directory weight
- Open File Manager To Directories (instead of jumping):

--purge deletes database entries that no longer exist on system
Instead of jumping to a directory, you can open a file explorer
window (Mac Finder, Windows Explorer, GNOME Nautilus, etc.) to the
directory instead.

-s, --stat show general stats and top 100 database entries
jo music

--version show version information and exit
Opening a file manager to a child directory is also supported.

ADVANCED USAGE
--------------
jco images

- Using Multiple Arguments
- Using Multiple Arguments:

Let's assume the following database:

Expand All @@ -142,132 +51,92 @@ ADVANCED USAGE

`j in` would jump into /home/user/mail/inbox as the higher weighted
entry. However you can pass multiple arguments to autojump to prefer
a different entry. In the above example, `j w in` would then jump
you into /home/user/work/inbox.

- Jump To A Child Directory.

Sometimes it's convenient to jump to a child directory
(sub-directory of current directory) rather than typing out the full
name.

jc images
a different entry. In the above example, `j w in` would then change
directory to /home/user/work/inbox.

- Open File Manager To Directories (instead of jumping)
For more options refer to help:

Instead of jumping to a directory, you can open a file explorer
window (Mac Finder, Windows Explorer, GNOME Nautilus, etc) to the
directory instead.

jo music
autojump --help

Opening a file manager to a child directory is also supported.
INSTALLATION
------------

jco images
### REQUIREMENTS

ADDITIONAL CONFIGURATION
------------------------
- Python v2.6+
- Bash v4.0+, zsh, or fish

- Enable ZSH Tab Completion
### AUTOMATIC

ZSH tab completion requires the `compinit` module to be loaded.
Please add the following line to your \~/.zshrc *after* loading
autojump:
#### Linux

autoload -U compinit && compinit
autojump is included in the following distro repositories, please use
relevant package management utilities to install (e.g. yum, apt-get,
etc):

For security compinit checks completion system if files will be
owned by root or the current user. This check can be ignored by
using the -u flag:
- Debian testing/unstable, Ubuntu, Linux Mint

autoload -U compinit && compinit -u
All Debian-derived distros require manual activation for policy
reasons, please see `/usr/share/doc/autojump/README.Debian`.

Tab completion requires two tabs before autojump will display the
completion menu. However if `setopt nolistambiguous` is enabled,
then only one tab is required.
- RedHat, Fedora, CentOS
- ArchLinux
- Gentoo
- Frugalware
- Slackware

- Always Ignore Case
#### OS X

Default behavior is to prioritize exact matches over all else. For
example, `j foo` will prefer /foobar over /FooBar even if the latter
has a higher weight. To change this behavior and ignore case, add
the following environmental variable in your \~/.bashrc:
Homebrew is the recommended installation method for Mac OS X:

export AUTOJUMP_IGNORE_CASE=1
brew install autojump

- Prefer Symbolic Links
MacPorts also available:

Default behavior is to evaluate symbolic links into full paths as to
reduce duplicate entries in the database. However, some users prefer
a shorter working directory path in their shell prompt. To switch
behavior to prefer symbolic links, add the following environmental
variable in your \~/.bashrc:
port install autojump

export AUTOJUMP_KEEP_SYMLINKS=1
### MANUAL

- Autocomplete Additional Commands (Bash only)
Grab a copy of autojump:

Autojump can be used to autocomplete other commands (e.g. cp or
vim). To use this feature, add the following environmental variable
in your \~/.bashrc:
git clone git://github.com/joelthelion/autojump.git

export AUTOJUMP_AUTOCOMPLETE_CMDS='cp vim'
Run the installation script and follow on screen instructions.

Changes require reloading autojump to take into effect.
cd autojump
./install.py or ./uinstall.py

KNOWN ISSUES
------------

- For bash users, autojump keeps track of directories as a pre-command
hook by modifying \$PROMPT\_COMMAND. If you overwrite
\$PROMPT\_COMMAND in \~/.bashrc you can cause problems. Don't do
this:
- autojump does not support directories that begin with `-`.

- For bash users, autojump keeps track of directories by modifying
`$PROMPT_COMMAND`. Do not overwrite `$PROMPT_COMMAND`:

export PROMPT_COMMAND="history -a"

Do this:
Instead append to the end of the existing $PROMPT\_COMMAND:

export PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND ;} history -a"

- The jump function `j` does not support directories that begin with
`-`. If you want to jump a directory called `--music`, try using
`j music` instead of `j --music`.

FILES
-----

If installed locally, autojump is self-contained in *\~/.autojump/*.

The database is stored in *\$XDG\_DATA\_HOME/autojump/autojump.txt*.

REPORTING BUGS
--------------

For any usage related issues or feature requests please visit:
For any questions or issues please visit:

*https://github.com/joelthelion/autojump/issues*

THANKS
------

Special thanks goes out to: Pierre Gueth, Simon Marache-Francisco,
Daniel Jackoway, and many others.
https://github.com/joelthelion/autojump/issues

AUTHORS
-------

autojump was originally written by Joël Schaerer, and currently
maintained by William Ting.
maintained by William Ting. More contributors can be found in `AUTHORS`.

COPYRIGHT
---------

Copyright © 2013 Free Software Foundation, Inc. License GPLv3+: GNU GPL
Copyright © 2012 Free Software Foundation, Inc. License GPLv3+: GNU GPL
version 3 or later <http://gnu.org/licenses/gpl.html>. This is free
software: you are free to change and redistribute it. There is NO
WARRANTY, to the extent permitted by law.

[dl]: https://github.com/joelthelion/autojump/downloads
[mock]: https://pypi.python.org/pypi/mock
[v12]: https://github.com/downloads/joelthelion/autojump/autojump_v12.tar.gz
[wiki]: https://github.com/joelthelion/autojump/wiki
Loading

0 comments on commit f5d13da

Please sign in to comment.