stow/oh-my-zsh/.oh-my-zsh/plugins/dirhistory/README.md

   1 # Dirhistory plugin
   2
   3 This plugin adds keyboard shortcuts for navigating directory history and hierarchy.
   4
   5 To use it, add `dirhistory` to the plugins array in your zshrc file:
   6
   7 ```zsh
   8 plugins=(... dirhistory)
   9 ```
  10
  11 ## Keyboard Shortcuts
  12
  13 | Shortcut                          | Description                                               |
  14 |-----------------------------------|-----------------------------------------------------------|
  15 | <kbd>Alt</kbd> + <kbd>Left</kbd>  | Go to previous directory                                  |
  16 | <kbd>Alt</kbd> + <kbd>Right</kbd> | Go to next directory                                      |
  17 | <kbd>Alt</kbd> + <kbd>Up</kbd>    | Move into the parent directory                            |
  18 | <kbd>Alt</kbd> + <kbd>Down</kbd>  | Move into the first child directory by alphabetical order |
  19
  20 **For macOS: use the Option key (<kbd>⌥</kbd>) instead of <kbd>Alt</kbd>**.
  21
  22 > NOTE: some terminals might override the <kbd>Alt</kbd> + Arrows key bindings (e.g. Windows Terminal).
  23 > If these don't work check your terminal settings and change them to a different keyboard shortcut.
  24
  25 ## Usage
  26
  27 This plugin allows you to navigate the history of previous working directories using <kbd>Alt</kbd> + <kbd>Left</kbd>
  28 and <kbd>Alt</kbd> + <kbd>Right</kbd>. <kbd>Alt</kbd> + <kbd>Left</kbd> moves to past directories, and
  29 <kbd>Alt</kbd> + <kbd>Right</kbd> goes back to recent directories.
  30
  31 **NOTE: the maximum directory history size is 30.**
  32
  33 You can also navigate **directory hierarchies** using <kbd>Alt</kbd> + <kbd>Up</kbd> and <kbd>Alt</kbd> + <kbd>Down</kbd>.
  34 <kbd>Alt</kbd> + <kbd>Up</kbd> moves to the parent directory, while <kbd>Alt</kbd> + <kbd>Down</kbd> moves into the first
  35 child directory found in alphabetical order (useful to navigate long empty directories, e.g. Java packages).
  36
  37 For example, if the shell was started, and the following commands were entered:
  38
  39 ```shell
  40 cd ~
  41 cd /usr
  42 cd share
  43 cd doc
  44 ```
  45
  46 the directory stack (`dirs -v`) would look like this:
  47
  48 ```console
  49 $ dirs -v
  50 0       /usr/share/doc
  51 1       /usr/share
  52 2       /usr
  53 3       ~
  54 ```
  55
  56 then entering <kbd>Alt</kbd> + <kbd>Left</kbd> at the prompt would change directory from `/usr/share/doc` to `/usr/share`,
  57 then if pressed again to `/usr`, then `~`. If <kbd>Alt</kbd> + <kbd>Right</kbd> were pressed the directory would be changed
  58 to `/usr` again.
  59
  60 After that, <kbd>Alt</kbd> + <kbd>Down</kbd> will probably go to `/usr/bin` if `bin` is the first directory in alphabetical
  61 order (depends on your `/usr` folder structure). <kbd>Alt</kbd> + <kbd>Up</kbd> will return to `/usr`, and once more will get
  62 you to the root folder (`/`).