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

   1 # dircycle
   2
   3 Plugin for cycling through the directory stack
   4
   5 This plugin enables directory navigation similar to using back and forward on browsers or common file explorers like Finder or Nautilus. It uses a small zle trick that lets you cycle through your directory stack left or right using <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd> / <kbd>Right</kbd> . This is useful when moving back and forth between directories in development environments, and can be thought of as kind of a nondestructive pushd/popd.
   6
   7 ## Enabling the plugin
   8
   9 1. Open your `.zshrc` file and add `dircycle` in the plugins section:
  10
  11    ```zsh
  12    plugins=(
  13        # all your enabled plugins
  14        dircycle
  15    )
  16    ```
  17
  18 2. Restart the shell or restart your Terminal session:
  19
  20    ```console
  21    $ exec zsh
  22    $
  23    ```
  24
  25 ## Usage Examples
  26
  27 Say you opened these directories on the terminal:
  28
  29 ```console
  30 ~$ cd Projects
  31 ~/Projects$ cd Hacktoberfest
  32 ~/Projects/Hacktoberfest$ cd oh-my-zsh
  33 ~/Projects/Hacktoberfest/oh-my-zsh$ dirs -v
  34 0       ~/Projects/Hacktoberfest/oh-my-zsh
  35 1       ~/Projects/Hacktoberfest
  36 2       ~/Projects
  37 3       ~
  38 ```
  39
  40 By pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>, the current working directory or `$CWD` will be from `oh-my-zsh` to `Hacktoberfest`. Press it again and it will be at `Projects`.
  41
  42 And by pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd>, the `$CWD` will be from `Projects` to `Hacktoberfest`. Press it again and it will be at `oh-my-zsh`.
  43
  44 Here's a example history table with the same accessed directories like above:
  45
  46 | Current `$CWD`  | Key press                                             | New `$CWD`      |
  47 | --------------- | ----------------------------------------------------- | --------------- |
  48 | `oh-my-zsh`     | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>  | `Hacktoberfest` |
  49 | `Hacktoberfest` | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>  | `Projects`      |
  50 | `Projects`      | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd>  | `~`             |
  51 | `~`             | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> | `Projects`      |
  52 | `Projects`      | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> | `Hacktoberfest` |
  53 | `Hacktoberfest` | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> | `oh-my-zsh`     |
  54 | `oh-my-zsh`     | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> | `~`             |
  55
  56 Note the last traversal, when pressing <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd> on a last known `$CWD`, it will change back to the first known `$CWD`, which in the example is `~`.
  57
  58 Here's an asciinema cast demonstrating the example above:
  59
  60 [![asciicast](https://asciinema.org/a/204406.png)](https://asciinema.org/a/204406)
  61
  62 ## Functions
  63
  64 | Function             | Description                                                                                               |
  65 | -------------------- | --------------------------------------------------------------------------------------------------------- |
  66 | `insert-cycledleft`  | Change `$CWD` to the previous known stack, binded on <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd> |
  67 | `insert-cycledright` | Change `$CWD` to the next known stack, binded on <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Right</kbd>    |
  68
  69 ## Rebinding keys
  70
  71 You can bind these functions to other key sequences, as long as you know the bindkey sequence. For example, these commands bind to <kbd>Alt</kbd> + <kbd>Shift</kbd> + <kbd>Left</kbd> / <kbd>Right</kbd> in `xterm-256color`:
  72
  73 ```zsh
  74 bindkey '^[[1;4D' insert-cycledleft
  75 bindkey '^[[1;4C' insert-cycledright
  76 ```
  77
  78 You can get the bindkey sequence by pressing <kbd>Ctrl</kbd> + <kbd>V</kbd>, then pressing the keyboard shortcut you want to use.