Merge pull request #243 from andyrichardson/patch-1

Update tpm_not_working.md

.gitattributes

@@ -0,0 +1,9 @@
+# Force text files to have unix eols, so Windows/Cygwin does not break them
+*.* eol=lf
+
+# These files are unfortunately not recognized as text files so
+# explicitly listing them here
+tpm eol=lf
+bin/* eol=lf
+bindings/* eol=lf
+tests/* eol=lf

.gitignore

@@ -1 +1,4 @@
 **/.vagrant/
+run_tests
+tests/run_tests_in_isolation
+tests/helpers/helpers.sh

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "lib/tmux-test"]
+	path = lib/tmux-test
+	url = https://github.com/tmux-plugins/tmux-test.git

.travis.yml

@@ -1,13 +1,19 @@
-# generic packages
+# generic packages and tmux
 before_install:
   - sudo apt-get update
   - sudo apt-get install -y git-core expect
   - sudo apt-get install -y python-software-properties software-properties-common
+  - sudo apt-get install -y libevent-dev libncurses-dev
+  - git clone https://github.com/tmux/tmux.git
+  - cd tmux
+  - git checkout 2.0
+  - sh autogen.sh
+  - ./configure && make && sudo make install
 
-# install latest Tmux 1.9a
 install:
-  - sudo add-apt-repository -y ppa:pi-rho/dev
-  - sudo apt-get update
-  - sudo apt-get install -y tmux=1.9a-1~ppa1~p
+  - git fetch --unshallow --recurse-submodules || git fetch --recurse-submodules
+  # manual `git clone` required for testing `tmux-test` plugin itself
+  - git clone https://github.com/tmux-plugins/tmux-test lib/tmux-test; true
+  - lib/tmux-test/setup
 
-script: ./tests/run-tests-within-vm
+script: ./tests/run_tests_in_isolation

CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ### master
 
+### v3.1.0, 2023-01-03
+- upgrade to new version of `tmux-test`
+- bug: when using `emacs` copy mode, Enter does not quit screen after tpm
+  installation/update. Fix by making `Escape` the key for emacs mode.
+- add a doc with troubleshooting instructions
+- add `.gitattributes` file that forces linefeed characters (classic `\n`) as
+  line endings - helps with misconfigured git on windows/cygwin
+- readme update: announce Cygwin support
+- un-deprecate old plugin definition syntax: `set -g @tpm_plugins`
+- More stuff, check `git log`.
+
+### v3.0.0, 2015-08-03
+- refactor `shared_set_tpm_path_constant` function
+- move all instructions to `docs/` dir
+- add `bin/install_plugins` cli executable script
+- improved test runner function
+- switch to using [tmux-test](https://github.com/tmux-plugins/tmux-test)
+  framework
+- add `bin/update_plugins` cli executable script
+- refactor test `expect` scripts, make them simpler and ensure they properly
+  assert expectations
+- refactor code that sets 'TMUX_PLUGIN_MANAGER_PATH' global env var
+- stop using global variable for 'tpm path'
+- support defining plugins via `set -g @plugin` in sourced files as well
+
+### v2.0.0, 2015-07-07
+- enable overriding default key bindings
+- start using `C-c` to clear screen
+- add uninstall/clean procedure and keybinding (prefix+alt+u) (@chilicuil)
+- add new `set @plugin 'repo'` plugin definition syntax (@chilicuil)
+- revert back to using `-g` flag in new plugin definition syntax
+- permit leading whitespace with new plugin definition syntax (thanks @chilicuil)
+- make sure `TMUX_PLUGIN_MANAGER_PATH` always has trailng slash
+- ensure old/deprecated plugin syntax `set -g @tpm_plugins` works alongside new
+  `set -g @plugin` syntax
+
+### v1.2.2, 2015-02-08
+- set GIT_TERMINAL_PROMPT=0 when doing `git clone`, `pull` or `submodule update`
+  to ensure git does not prompt for username/password in any case
+
 ### v1.2.1, 2014-11-21
 - change the way plugin name is expanded. It now uses the http username
   and password by default, like this: `https://git::@github.com/`. This prevents

HOW_TO_PLUGIN.md

@@ -1,113 +1,2 @@
-# How to create Tmux plugins
-
-Creating a new plugin is easy.
-
-For demonstration purposes we'll create a simple plugin that lists all
-installed TPM plugins. Yes, a plugin that lists plugins :) We'll bind that to
-`prefix + T`.
-
-### 1. create a new git project
-
-TPM depends on git for downloading and updating plugins.
-
-To create a new git project:
-
-    $ mkdir tmux_my_plugin
-    $ cd tmux_my_plugin
-    $ git init
-
-### 2. create a `*.tmux` plugin run file
-
-When it sources a plugin, TPM executes all `*.tmux` files in your plugins'
-directory. That's how plugins are run.
-
-Create a plugin run file in plugin directory:
-
-    $ touch my_plugin.tmux
-    $ chmod +x my_plugin.tmux
-
-You can have more than one `*.tmux` file, and all will get executed. Usually
-however, you'll need just one.
-
-### 3. create a plugin key binding
-
-We want the behavior of the plugin to trigger when a user hits `prefix + T`.
-
-Key `T` is chosen because:
- - it's "kind of" a mnemonic for `TPM`
- - the key is not used by Tmux natively. Tmux man page, KEY BINDINGS section
-   contains a list of all the bindings Tmux uses. We don't want to override any
-   Tmux default binding, and there's plenty of unused keys.
-
-Open the plugin run file in your favorite text editor:
-
-    $ vim my_plugin.tmux
-    # or
-    $ subl my_plugin.tmux
-
-Put the following content in the file:
-
-    #!/usr/bin/env bash
-
-    CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-    tmux bind-key T run-shell "$CURRENT_DIR/scripts/tmux_list_plugins.sh"
-
-As you can see, plugin run file is a simple bash script that sets up binding.
-
-When pressed, `prefix + T` will now execute another shell script:
-`tmux_list_plugins.sh`. That script should be in `scripts/` directory -
-relative to the plugin run file.
-
-
-### 4. listing plugins
-
-Now that we have the binding, let's create a script that's invoked on
-`prefix + T`.
-
-    $ mkdir scripts
-    $ touch scripts/tmux_list_plugins.sh
-    $ chmod +x scripts/tmux_list_plugins.sh
-
-And here's the script content:
-
-    #!/usr/bin/env bash
-
-    # fetching the value of "tpm_plugins" option
-    plugins_list=$(tmux show-option -gqv "@tpm_plugins")
-
-    # displaying variable content, line by line
-    for plugin in $plugins_list; do
-        echo $plugin
-    done
-
-### 5. try it out
-
-To try if this works, execute the plugin run file:
-
-    $ ./my_plugin.tmux
-
-That should set up the key binding. Now hit `prefix + T` and see if it works.
-
-If you get stuck you can download and check this tutorial
-[plugin here](https://github.com/tmux-plugins/tmux-example-plugin).
-
-### 6. publish the plugin
-
-When everything works, push the plugin to an online git repository, preferably
-Github.
-
-Other users can install your plugin by just adding plugin git URL to the
-`@tpm_plugins` list in their `.tmux.conf`.
-
-If the plugin is on Github, your users will be able to use the shorthand of
-`github_username/repository`.
-
-### Conclusion
-
-Hopefully, that was easy. As you can see, it's mostly shell scripting.
-
-You can also check source code of other plugins from the
-[List of plugins](PLUGINS.md).
-
-You can use other scripting languages (ruby, phyton etc), but plain old shell
-is preferred because it will work almost anywhere.
+Instructions moved to
+[docs/how_to_create_plugin.md](docs/how_to_create_plugin.md).

README.md

@@ -1,8 +1,12 @@
 # Tmux Plugin Manager
 
-[![Build Status](https://travis-ci.org/tmux-plugins/tpm.png?branch=master)](https://travis-ci.org/tmux-plugins/tpm)
+[![Build Status](https://travis-ci.org/tmux-plugins/tpm.svg?branch=master)](https://travis-ci.org/tmux-plugins/tpm)
 
-Installs and loads TMUX plugins.
+Installs and loads `tmux` plugins.
+
+Tested and working on Linux, OSX, and Cygwin.
+
+See list of plugins [here](https://github.com/tmux-plugins/list).
 
 ### Installation
 
@@ -10,79 +14,87 @@ Requirements: `tmux` version 1.9 (or higher), `git`, `bash`.
 
 Clone TPM:
 
-    $ git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
+```bash
+git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
+```
 
-Put this at the bottom of your `.tmux.conf` (backslashes at the end of the lines
-are required):
+Put this at the bottom of `~/.tmux.conf` (`$XDG_CONFIG_HOME/tmux/tmux.conf`
+works too):
 
-    # List of plugins
-    # Supports `github_username/repo` or full git repo URLs
-    set -g @tpm_plugins '              \
-      tmux-plugins/tpm                 \
-      tmux-plugins/tmux-sensible       \
-    '
-    # Other examples:
-    # github_username/plugin_name    \
-    # git@github.com/user/plugin     \
-    # git@bitbucket.com/user/plugin  \
+```bash
+# List of plugins
+set -g @plugin 'tmux-plugins/tpm'
+set -g @plugin 'tmux-plugins/tmux-sensible'
 
-    # Initializes TMUX plugin manager.
-    # Keep this line at the very bottom of tmux.conf.
-    run-shell '~/.tmux/plugins/tpm/tpm'
+# Other examples:
+# set -g @plugin 'github_username/plugin_name'
+# set -g @plugin 'github_username/plugin_name#branch'
+# set -g @plugin 'git@github.com:user/plugin'
+# set -g @plugin 'git@bitbucket.com:user/plugin'
+
+# Initialize TMUX plugin manager (keep this line at the very bottom of tmux.conf)
+run '~/.tmux/plugins/tpm/tpm'
+```
 
 Reload TMUX environment so TPM is sourced:
 
-    # type this in terminal
-    $ tmux source-file ~/.tmux.conf
+```bash
+# type this in terminal if tmux is already running
+tmux source ~/.tmux.conf
+```
 
 That's it!
 
 ### Installing plugins
 
-1. add a new plugin to the `@tpm_plugins` list
-2. hit `prefix + I` (I as in *I*nstall) to fetch the plugin
+1. Add new plugin to `~/.tmux.conf` with `set -g @plugin '...'`
+2. Press `prefix` + <kbd>I</kbd> (capital i, as in **I**nstall) to fetch the plugin.
 
 You're good to go! The plugin was cloned to `~/.tmux/plugins/` dir and sourced.
 
 ### Uninstalling plugins
 
-1. remove plugin from `@tpm_plugins` list
-2. All the plugins are installed to `~/.tmux/plugins/`. Find plugin
-  directory there and just remove it.
+1. Remove (or comment out) plugin from the list.
+2. Press `prefix` + <kbd>alt</kbd> + <kbd>u</kbd> (lowercase u as in **u**ninstall) to remove the plugin.
+
+All the plugins are installed to `~/.tmux/plugins/` so alternatively you can
+find plugin directory there and remove it.
 
 ### Key bindings
 
-`prefix + I`
-- installs new plugins from github or any other git repo
-- refreshes TMUX environment
+`prefix` + <kbd>I</kbd>
+- Installs new plugins from GitHub or any other git repository
+- Refreshes TMUX environment
 
-`prefix + U`
+`prefix` + <kbd>U</kbd>
 - updates plugin(s)
 
-### List of plugins
+`prefix` + <kbd>alt</kbd> + <kbd>u</kbd>
+- remove/uninstall plugins not on the plugin list
 
-For more plugins, check [here](https://github.com/tmux-plugins).
+### Docs
 
-### Wiki pages
+- [Help, tpm not working](docs/tpm_not_working.md) - problem solutions
 
-More advanced features, regular users probably do not need this:
+More advanced features and instructions, regular users probably do not need
+this:
 
-- [installing plugins via the command line](https://github.com/tmux-plugins/tpm/wiki/Installing-plugins-via-the-command-line-only)
-- [changing plugins install dir](https://github.com/tmux-plugins/tpm/wiki/Changing-plugins-install-dir)
-
-### Creating plugins
-
-[How to create a plugin](HOW_TO_PLUGIN.md). It's easy.
+- [How to create a plugin](docs/how_to_create_plugin.md). It's easy.
+- [Managing plugins via the command line](docs/managing_plugins_via_cmd_line.md)
+- [Changing plugins install dir](docs/changing_plugins_install_dir.md)
+- [Automatic TPM installation on a new machine](docs/automatic_tpm_installation.md)
 
 ### Tests
 
-Tests run on [travis](https://travis-ci.org/tmux-plugins/tpm).
+Tests for this project run on [Travis CI](https://travis-ci.org/tmux-plugins/tpm).
 
 When run locally, [vagrant](https://www.vagrantup.com/) is required.
 Run tests with:
 
-    # within project directory
-    $ ./run-tests
+```bash
+# within project directory
+./run_tests
+```
 
 ### License
 

Vagrantfile

@@ -1,10 +0,0 @@
-VAGRANTFILE_API_VERSION = '2'
-
-Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
-  config.vm.box = 'precise32'
-  config.vm.box_url = 'http://files.vagrantup.com/precise32.box'
-
-  config.vm.synced_folder './', '/home/vagrant/tpm'
-
-  config.vm.provision 'shell', path: 'vagrant_provisioning.sh'
-end

bin/clean_plugins

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# Script intended for use via the command line.
+#
+# `.tmux.conf` needs to be set for TPM. Tmux has to be installed on the system,
+# but does not need to be started in order to run this script.
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPTS_DIR="$CURRENT_DIR/../scripts"
+
+main() {
+	"$SCRIPTS_DIR/clean_plugins.sh" # has correct exit code
+}
+main

bin/install_plugins

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# Script intended for use via the command line.
+#
+# `.tmux.conf` needs to be set for TPM. Tmux has to be installed on the system,
+# but does not need to be started in order to run this script.
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPTS_DIR="$CURRENT_DIR/../scripts"
+
+main() {
+	"$SCRIPTS_DIR/install_plugins.sh" # has correct exit code
+}
+main

bin/update_plugins

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+# Script intended for use via the command line.
+#
+# `.tmux.conf` needs to be set for TPM. Tmux has to be installed on the system,
+# but does not need to be started in order to run this script.
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPTS_DIR="$CURRENT_DIR/../scripts"
+PROGRAM_NAME="$0"
+
+if [ $# -eq 0 ]; then
+	echo "usage:"
+	echo "  $PROGRAM_NAME all                   update all plugins"
+	echo "  $PROGRAM_NAME tmux-foo              update plugin 'tmux-foo'"
+	echo "  $PROGRAM_NAME tmux-bar tmux-baz     update multiple plugins"
+	exit 1
+fi
+
+main() {
+	"$SCRIPTS_DIR/update_plugin.sh" --shell-echo "$*" # has correct exit code
+}
+main "$*"
+

bindings/clean_plugins

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+# Tmux key-binding script.
+# Scripts intended to be used via the command line are in `bin/` directory.
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPTS_DIR="$CURRENT_DIR/../scripts"
+HELPERS_DIR="$SCRIPTS_DIR/helpers"
+
+source "$HELPERS_DIR/tmux_echo_functions.sh"
+source "$HELPERS_DIR/tmux_utils.sh"
+
+main() {
+	reload_tmux_environment
+	"$SCRIPTS_DIR/clean_plugins.sh" --tmux-echo >/dev/null 2>&1
+	reload_tmux_environment
+	end_message
+}
+main

bindings/install_plugins

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+# Tmux key-binding script.
+# Scripts intended to be used via the command line are in `bin/` directory.
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPTS_DIR="$CURRENT_DIR/../scripts"
+HELPERS_DIR="$SCRIPTS_DIR/helpers"
+
+source "$HELPERS_DIR/tmux_echo_functions.sh"
+source "$HELPERS_DIR/tmux_utils.sh"
+
+main() {
+	reload_tmux_environment
+	"$SCRIPTS_DIR/install_plugins.sh" --tmux-echo >/dev/null 2>&1
+	reload_tmux_environment
+	end_message
+}
+main

bindings/update_plugins

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+# Tmux key-binding script.
+# Scripts intended to be used via the command line are in `bin/` directory.
+
+# This script:
+# - shows a list of installed plugins
+# - starts a prompt to enter the name of the plugin that will be updated
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SCRIPTS_DIR="$CURRENT_DIR/../scripts"
+HELPERS_DIR="$SCRIPTS_DIR/helpers"
+
+source "$HELPERS_DIR/plugin_functions.sh"
+source "$HELPERS_DIR/tmux_echo_functions.sh"
+source "$HELPERS_DIR/tmux_utils.sh"
+
+display_plugin_update_list() {
+	local plugins="$(tpm_plugins_list_helper)"
+	tmux_echo "Installed plugins:"
+	tmux_echo ""
+
+	for plugin in $plugins; do
+		# displaying only installed plugins
+		if plugin_already_installed "$plugin"; then
+			local plugin_name="$(plugin_name_helper "$plugin")"
+			tmux_echo "  $plugin_name"
+		fi
+	done
+
+	tmux_echo ""
+	tmux_echo "Type plugin name to update it."
+	tmux_echo ""
+	tmux_echo "- \"all\" - updates all plugins"
+	tmux_echo "- ENTER - cancels"
+}
+
+update_plugin_prompt() {
+	tmux command-prompt -p 'plugin update:' " \
+		send-keys C-c; \
+		run-shell '$SCRIPTS_DIR/update_plugin_prompt_handler.sh %1'"
+}
+
+main() {
+	reload_tmux_environment
+	display_plugin_update_list
+	update_plugin_prompt
+}
+main

docs/automatic_tpm_installation.md

@@ -0,0 +1,12 @@
+# Automatic tpm installation
+
+One of the first things we do on a new machine is cloning our dotfiles. Not everything comes with them though, so for example `tpm` most likely won't be installed.
+
+If you want to install `tpm` and plugins automatically when tmux is started, put the following snippet in `.tmux.conf` before the final `run '~/.tmux/plugins/tpm/tpm'`:
+
+```
+if "test ! -d ~/.tmux/plugins/tpm" \
+   "run 'git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm && ~/.tmux/plugins/tpm/bin/install_plugins'"
+```
+
+This useful tip was submitted by @acr4 and narfman0.

docs/changing_plugins_install_dir.md

@@ -0,0 +1,16 @@
+# Changing plugins install dir
+
+By default, TPM installs plugins in a subfolder named `plugins/` inside
+`$XDG_CONFIG_HOME/tmux/` if a `tmux.conf` file was found at that location, or
+inside `~/.tmux/` otherwise.
+
+You can change the install path by putting this in `.tmux.conf`:
+
+    set-environment -g TMUX_PLUGIN_MANAGER_PATH '/some/other/path/'
+
+Tmux plugin manager initialization in `.tmux.conf` should also be updated:
+
+    # initializes TMUX plugin manager in a new path
+    run /some/other/path/tpm/tpm
+
+Please make sure that the `run` line is at the very bottom of `.tmux.conf`.

docs/how_to_create_plugin.md

@@ -0,0 +1,108 @@
+# How to create Tmux plugins
+
+Creating a new plugin is easy.
+
+For demonstration purposes we'll create a simple plugin that lists all
+installed TPM plugins. Yes, a plugin that lists plugins :) We'll bind that to
+`prefix + T`.
+
+The source code for this example plugin can be found
+[here](https://github.com/tmux-plugins/tmux-example-plugin).
+
+### 1. create a new git project
+
+TPM depends on git for downloading and updating plugins.
+
+To create a new git project:
+
+    $ mkdir tmux_my_plugin
+    $ cd tmux_my_plugin
+    $ git init
+
+### 2. create a `*.tmux` plugin run file
+
+When it sources a plugin, TPM executes all `*.tmux` files in your plugins'
+directory. That's how plugins are run.
+
+Create a plugin run file in plugin directory:
+
+    $ touch my_plugin.tmux
+    $ chmod u+x my_plugin.tmux
+
+You can have more than one `*.tmux` file, and all will get executed. However, usually
+you'll need just one.
+
+### 3. create a plugin key binding
+
+We want the behavior of the plugin to trigger when a user hits `prefix + T`.
+
+Key `T` is chosen because:
+ - it's "kind of" a mnemonic for `TPM`
+ - the key is not used by Tmux natively. Tmux man page, KEY BINDINGS section
+   contains a list of all the bindings Tmux uses. There's plenty of unused keys
+   and we don't want to override any of Tmux default key bindings.
+
+Open the plugin run file in your favorite text editor:
+
+    $ vim my_plugin.tmux
+    # or
+    $ subl my_plugin.tmux
+
+Put the following content in the file:
+
+    #!/usr/bin/env bash
+
+    CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+    tmux bind-key T run-shell "$CURRENT_DIR/scripts/tmux_list_plugins.sh"
+
+As you can see, plugin run file is a simple bash script that sets up the binding.
+
+When pressed, `prefix + T` will execute another shell script:
+`tmux_list_plugins.sh`. That script should be in `scripts/` directory -
+relative to the plugin run file.
+
+
+### 4. listing plugins
+
+Now that we have the binding, let's create a script that's invoked with
+`prefix + T`.
+
+    $ mkdir scripts
+    $ touch scripts/tmux_list_plugins.sh
+    $ chmod u+x scripts/tmux_list_plugins.sh
+
+And here's the script content:
+
+    #!/usr/bin/env bash
+
+    # fetching the directory where plugins are installed
+    plugin_path="$(tmux show-env -g TMUX_PLUGIN_MANAGER_PATH | cut -f2 -d=)"
+
+    # listing installed plugins
+    ls -1 "$plugin_path"
+
+### 5. try it out
+
+To see if this works, execute the plugin run file:
+
+    $ ./my_plugin.tmux
+
+That should set up the key binding. Now hit `prefix + T` and see if it works.
+
+### 6. publish the plugin
+
+When everything is ready, push the plugin to an online git repository,
+preferably GitHub.
+
+Other users can install your plugin by just adding plugin git URL to the
+`@plugin` list in their `.tmux.conf`.
+
+If the plugin is on GitHub, your users will be able to use the shorthand of
+`github_username/repository`.
+
+### Conclusion
+
+Hopefully, that was easy. As you can see, it's mostly shell scripting.
+
+You can use other scripting languages (ruby, python etc) but plain old shell
+is preferred because of portability.

docs/managing_plugins_via_cmd_line.md

@@ -0,0 +1,36 @@
+# Managing plugins via the command line
+
+Aside from tmux key bindings, TPM provides shell interface for managing plugins
+via scripts located in [bin/](../bin/) directory.
+
+Tmux does not need to be started in order to run scripts (but it's okay if it
+is). If you [changed tpm install dir](../docs/changing_plugins_install_dir.md)
+in `.tmux.conf` that should work fine too.
+
+Prerequisites:
+
+- tmux installed on the system (doh)
+- `.tmux.conf` set up for TPM
+
+### Installing plugins
+
+As usual, plugins need to be specified in `.tmux.conf`. Run the following
+command to install plugins:
+
+    ~/.tmux/plugins/tpm/bin/install_plugins
+
+### Updating plugins
+
+To update all installed plugins:
+
+    ~/.tmux/plugins/tpm/bin/update_plugins all
+
+or update a single plugin:
+
+    ~/.tmux/plugins/tpm/bin/update_plugins tmux-sensible
+
+### Removing plugins
+
+To remove plugins not on the plugin list:
+
+    ~/.tmux/plugins/tpm/bin/clean_plugins

docs/tpm_not_working.md

@@ -0,0 +1,102 @@
+# Help, tpm not working!
+
+Here's the list of issues users had with `tpm`:
+
+<hr />
+
+> Nothing works. `tpm` key bindings `prefix + I`, `prefix + U` not even
+  defined.
+
+Related [issue #22](https://github.com/tmux-plugins/tpm/issues/22)
+
+- Do you have required `tmux` version to run `tpm`?<br/>
+  Check `tmux` version with `$ tmux -V` command and make sure it's higher or
+  equal to the required version for `tpm` as stated in the readme.
+
+- ZSH tmux plugin might be causing issues.<br/>
+  If you have it installed, try disabling it and see if `tpm` works then.
+
+<hr />
+
+> Help, I'm using custom config file with `tmux -f /path/to/my_tmux.conf`
+to start Tmux and for some reason plugins aren't loaded!?
+
+Related [issue #57](https://github.com/tmux-plugins/tpm/issues/57)
+
+`tpm` has a known issue when using custom config file with `-f` option.
+The solution is to use alternative plugin definition syntax. Here are the steps
+to make it work:
+
+1. remove all `set -g @plugin` lines from tmux config file
+2. in the config file define the plugins in the following way:
+
+        # List of plugins
+        set -g @tpm_plugins '          \
+          tmux-plugins/tpm             \
+          tmux-plugins/tmux-sensible   \
+          tmux-plugins/tmux-resurrect  \
+        '
+
+        # Initialize TMUX plugin manager (keep this line at the very bottom of tmux.conf)
+        run '~/.tmux/plugins/tpm/tpm'
+
+3. Reload TMUX environment so TPM is sourced: `$ tmux source /path/to/my_tmux.conf`
+
+The plugins should now be working.
+
+<hr />
+
+> Weird sequence of characters show up when installing or updating plugins
+
+Related: [issue #25](https://github.com/tmux-plugins/tpm/issues/25)
+
+- This could be caused by [tmuxline.vim](https://github.com/edkolev/tmuxline.vim)
+  plugin. Uninstall it and see if things work.
+
+<hr />
+
+> "failed to connect to server" error when sourcing .tmux.conf
+
+Related: [issue #48](https://github.com/tmux-plugins/tpm/issues/48)
+
+- Make sure `tmux source ~/.tmux.conf` command is ran from inside `tmux`.
+
+<hr />
+
+> tpm not working: '~/.tmux/plugins/tpm/tpm' returned 2 (Windows / Cygwin)
+
+Related: [issue #81](https://github.com/tmux-plugins/tpm/issues/81)
+
+This issue is most likely caused by Windows line endings. For example, if you
+have git's `core.autocrlf` option set to `true`, git will automatically convert
+all the files to Windows line endings which might cause a problem.
+
+The solution is to convert all line ending to Unix newline characters. This
+command handles that for all files under `.tmux/` dir (skips `.git`
+subdirectories):
+
+```bash
+find ~/.tmux -type d -name '.git*' -prune -o -type f -print0 | xargs -0 dos2unix
+```
+
+<hr />
+
+> '~/.tmux/plugins/tpm/tpm' returned 127 (on macOS, w/ tmux installed using brew)
+
+Related: [issue #67](https://github.com/tmux-plugins/tpm/issues/67)
+
+This problem is because tmux's `run-shell` command runs a shell which doesn't read from user configs, thus tmux installed in a brew prefix (e.g. `/usr/local/bin`) will not be found.
+
+The solution is to find your brew prefix
+
+```sh
+> echo "$(brew --prefix)/bin"
+/opt/homebrew/bin
+```
+
+And prepend it to the `PATH` environment variable
+```
+set-environment -g PATH "/opt/homebrew/bin:/bin:/usr/bin"
+```
+
+before any `run-shell`/`run` commands in `~/.tmux.conf`.

lib/tmux-test

@@ -0,0 +1 @@
+Subproject commit 33fa65fbfb72ba6dd106c21bf5ee6cc353ecdbb6

run-tests

@@ -1,31 +0,0 @@
-#!/usr/bin/env bash
-
-CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-
-# running test suite is successful by default
-tests_exit_value=0
-
-run_vagrant() {
-	vagrant up
-}
-
-# Halt vagrant after tests are done running, unless KEEP_RUNNING environment
-# variable is set to 'true'.
-stop_vagrant() {
-	if [ -z "$KEEP_RUNNING" ]; then
-		vagrant halt
-	fi
-}
-
-run_tests() {
-	vagrant ssh -c "cd ~/tpm; ./tests/run-tests-within-vm"
-	tests_exit_value=$?
-}
-
-main() {
-	run_vagrant
-	run_tests
-	stop_vagrant
-	exit "$tests_exit_value"
-}
-main

scripts/clean_plugins.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+HELPERS_DIR="$CURRENT_DIR/helpers"
+
+source "$HELPERS_DIR/plugin_functions.sh"
+source "$HELPERS_DIR/utility.sh"
+
+if [ "$1" == "--tmux-echo" ]; then # tmux-specific echo functions
+	source "$HELPERS_DIR/tmux_echo_functions.sh"
+else # shell output functions
+	source "$HELPERS_DIR/shell_echo_functions.sh"
+fi
+
+clean_plugins() {
+	local plugins plugin plugin_directory
+	plugins="$(tpm_plugins_list_helper)"
+
+	for plugin_directory in "$(tpm_path)"/*; do
+		[ -d "${plugin_directory}" ] || continue
+		plugin="$(plugin_name_helper "${plugin_directory}")"
+		case "${plugins}" in
+			*"${plugin}"*) : ;;
+			*)
+			[ "${plugin}" = "tpm" ] && continue
+			echo_ok "Removing \"$plugin\""
+			rm -rf "${plugin_directory}" >/dev/null 2>&1
+			[ -d "${plugin_directory}" ] &&
+			echo_err "  \"$plugin\" clean fail" ||
+			echo_ok "  \"$plugin\" clean success"
+			;;
+		esac
+	done
+}
+
+main() {
+	ensure_tpm_path_exists
+	clean_plugins
+	exit_value_helper
+}
+main

scripts/helpers/plugin_functions.sh

@@ -0,0 +1,104 @@
+# using @tpm_plugins is now deprecated in favor of using @plugin syntax
+tpm_plugins_variable_name="@tpm_plugins"
+
+# manually expanding tilde char or `$HOME` variable.
+_manual_expansion() {
+	local path="$1"
+	local expanded_tilde="${path/#\~/$HOME}"
+	echo "${expanded_tilde/#\$HOME/$HOME}"
+}
+
+_tpm_path() {
+	local string_path="$(tmux start-server\; show-environment -g TMUX_PLUGIN_MANAGER_PATH | cut -f2 -d=)/"
+	_manual_expansion "$string_path"
+}
+
+_CACHED_TPM_PATH="$(_tpm_path)"
+
+# Get the absolute path to the users configuration file of TMux.
+# This includes a prioritized search on different locations.
+#
+_get_user_tmux_conf() {
+	# Define the different possible locations.
+	xdg_location="${XDG_CONFIG_HOME:-$HOME/.config}/tmux/tmux.conf"
+	default_location="$HOME/.tmux.conf"
+
+	# Search for the correct configuration file by priority.
+	if [ -f "$xdg_location" ]; then
+		echo "$xdg_location"
+
+	else
+		echo "$default_location"
+	fi
+}
+
+_tmux_conf_contents() {
+	user_config=$(_get_user_tmux_conf)
+	cat /etc/tmux.conf "$user_config" 2>/dev/null
+	if [ "$1" == "full" ]; then # also output content from sourced files
+		local file
+		for file in $(_sourced_files); do
+			cat $(_manual_expansion "$file") 2>/dev/null
+		done
+	fi
+}
+
+# return files sourced from tmux config files
+_sourced_files() {
+	_tmux_conf_contents |
+		sed -E -n -e "s/^[[:space:]]*source(-file)?[[:space:]]+(-q+[[:space:]]+)?['\"]?([^'\"]+)['\"]?/\3/p"
+}
+
+# Want to be able to abort in certain cases
+trap "exit 1" TERM
+export TOP_PID=$$
+
+_fatal_error_abort() {
+	echo >&2 "Aborting."
+	kill -s TERM $TOP_PID
+}
+
+# PUBLIC FUNCTIONS BELOW
+
+tpm_path() {
+	if [ "$_CACHED_TPM_PATH" == "/" ]; then
+		echo >&2 "FATAL: Tmux Plugin Manager not configured in tmux.conf"
+		_fatal_error_abort
+	fi
+	echo "$_CACHED_TPM_PATH"
+}
+
+tpm_plugins_list_helper() {
+	# lists plugins from @tpm_plugins option
+	echo "$(tmux start-server\; show-option -gqv "$tpm_plugins_variable_name")"
+
+	# read set -g @plugin "tmux-plugins/tmux-example-plugin" entries
+	_tmux_conf_contents "full" |
+		awk '/^[ \t]*set(-option)? +-g +@plugin/ { gsub(/'\''/,""); gsub(/'\"'/,""); print $4 }'
+}
+
+# Allowed plugin name formats:
+# 1. "git://github.com/user/plugin_name.git"
+# 2. "user/plugin_name"
+plugin_name_helper() {
+	local plugin="$1"
+	# get only the part after the last slash, e.g. "plugin_name.git"
+	local plugin_basename="$(basename "$plugin")"
+	# remove ".git" extension (if it exists) to get only "plugin_name"
+	local plugin_name="${plugin_basename%.git}"
+	echo "$plugin_name"
+}
+
+plugin_path_helper() {
+	local plugin="$1"
+	local plugin_name="$(plugin_name_helper "$plugin")"
+	echo "$(tpm_path)${plugin_name}/"
+}
+
+plugin_already_installed() {
+	local plugin="$1"
+	local plugin_path="$(plugin_path_helper "$plugin")"
+	[ -d "$plugin_path" ] &&
+		cd "$plugin_path" &&
+		git remote >/dev/null 2>&1
+}

scripts/helpers/shell_echo_functions.sh

@@ -0,0 +1,7 @@
+echo_ok() {
+	echo "$*"
+}
+
+echo_err() {
+	fail_helper "$*"
+}

scripts/helpers/tmux_echo_functions.sh

@@ -0,0 +1,28 @@
+_has_emacs_mode_keys() {
+	$(tmux show -gw mode-keys | grep -q emacs)
+}
+
+tmux_echo() {
+	local message="$1"
+	tmux run-shell "echo '$message'"
+}
+
+echo_ok() {
+	tmux_echo "$*"
+}
+
+echo_err() {
+	tmux_echo "$*"
+}
+
+end_message() {
+	if _has_emacs_mode_keys; then
+		local continue_key="ESCAPE"
+	else
+		local continue_key="ENTER"
+	fi
+	tmux_echo ""
+	tmux_echo "TMUX environment reloaded."
+	tmux_echo ""
+	tmux_echo "Done, press $continue_key to continue."
+}

scripts/helpers/tmux_utils.sh

@@ -0,0 +1,6 @@
+HELPERS_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$HELPERS_DIR/plugin_functions.sh"
+
+reload_tmux_environment() {
+	tmux source-file $(_get_user_tmux_conf) >/dev/null 2>&1
+}

scripts/helpers/utility.sh

@@ -0,0 +1,17 @@
+ensure_tpm_path_exists() {
+	mkdir -p "$(tpm_path)"
+}
+
+fail_helper() {
+	local message="$1"
+	echo "$message" >&2
+	FAIL="true"
+}
+
+exit_value_helper() {
+	if [ "$FAIL" == "true" ]; then
+		exit 1
+	else
+		exit 0
+	fi
+}

scripts/install_plugins.sh

@@ -1,62 +1,75 @@
 #!/usr/bin/env bash
 
 CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+HELPERS_DIR="$CURRENT_DIR/helpers"
 
-source "$CURRENT_DIR/shared_functions.sh"
+source "$HELPERS_DIR/plugin_functions.sh"
+source "$HELPERS_DIR/utility.sh"
+
+if [ "$1" == "--tmux-echo" ]; then # tmux-specific echo functions
+	source "$HELPERS_DIR/tmux_echo_functions.sh"
+else # shell output functions
+	source "$HELPERS_DIR/shell_echo_functions.sh"
+fi
 
 clone() {
-	local plugin=$1
-	cd $SHARED_TPM_PATH &&
-		git clone --recursive $plugin
+	local plugin="$1"
+	local branch="$2"
+	if [ -n "$branch" ]; then
+		cd "$(tpm_path)" &&
+			GIT_TERMINAL_PROMPT=0 git clone -b "$branch" --single-branch --recursive "$plugin" >/dev/null 2>&1
+	else
+		cd "$(tpm_path)" &&
+			GIT_TERMINAL_PROMPT=0 git clone --single-branch --recursive "$plugin" >/dev/null 2>&1
+	fi
 }
 
 # tries cloning:
 # 1. plugin name directly - works if it's a valid git url
-# 2. expands the plugin name to point to a github repo and tries cloning again
+# 2. expands the plugin name to point to a GitHub repo and tries cloning again
 clone_plugin() {
-	local plugin=$1
-	clone "$plugin" ||
-		clone "https://git::@github.com/$plugin"
+	local plugin="$1"
+	local branch="$2"
+	clone "$plugin" "$branch" ||
+		clone "https://git::@github.com/$plugin" "$branch"
 }
 
-# pull new changes or clone plugin
+# clone plugin and produce output
 install_plugin() {
 	local plugin="$1"
-	local plugin_name="$(shared_plugin_name "$plugin")"
+	local branch="$2"
+	local plugin_name="$(plugin_name_helper "$plugin")"
 
 	if plugin_already_installed "$plugin"; then
-		# plugin is already installed
-		echo_message "Already installed \"$plugin_name\""
+		echo_ok "Already installed \"$plugin_name\""
 	else
-		# plugin wasn't cloned so far - clone it
-		echo_message "Installing \"$plugin_name\""
-		clone_plugin "$plugin" &&
-			echo_message "  \"$plugin_name\" download success" ||
-			echo_message "  \"$plugin_name\" download fail"
+		echo_ok "Installing \"$plugin_name\""
+		clone_plugin "$plugin" "$branch" &&
+			echo_ok "  \"$plugin_name\" download success" ||
+			echo_err "  \"$plugin_name\" download fail"
 	fi
 }
 
 install_plugins() {
-	local plugins=$(shared_get_tpm_plugins_list)
+	local plugins="$(tpm_plugins_list_helper)"
 	for plugin in $plugins; do
-		install_plugin "$plugin"
+		IFS='#' read -ra plugin <<< "$plugin"
+		install_plugin "${plugin[0]}" "${plugin[1]}"
 	done
 }
 
-ensure_tpm_path_exists() {
-	mkdir -p $SHARED_TPM_PATH
-}
-
-reload_tmux_environment() {
-	tmux source-file ~/.tmux.conf >/dev/null 2>&1
+verify_tpm_path_permissions() {
+	local path="$(tpm_path)"
+	# check the write permission flag for all users to ensure
+	# that we have proper access
+	[ -w "$path" ] ||
+		echo_err "$path is not writable!"
 }
 
 main() {
-	reload_tmux_environment
-	shared_set_tpm_path_constant
 	ensure_tpm_path_exists
+	verify_tpm_path_permissions
 	install_plugins
-	reload_tmux_environment
-	end_message
+	exit_value_helper
 }
 main

scripts/set_tpm_path.sh

@@ -1,22 +0,0 @@
-#!/usr/bin/env bash
-
-default_tpm_path="$HOME/.tmux/plugins/"
-
-tpm_path_set() {
-	tmux show-environment -g TMUX_PLUGIN_MANAGER_PATH
-}
-
-set_default_tpm_path() {
-	tmux set-environment -g TMUX_PLUGIN_MANAGER_PATH "$default_tpm_path"
-}
-
-ensure_tpm_path() {
-	if ! tpm_path_set; then
-		set_default_tpm_path
-	fi
-}
-
-main() {
-	ensure_tpm_path
-}
-main

scripts/shared_functions.sh

@@ -1,84 +0,0 @@
-# shared functions and constants
-
-tpm_plugins_variable_name="@tpm_plugins"
-SHARED_TPM_PATH=""
-
-# sets a "global variable" for the current file
-shared_set_tpm_path_constant() {
-	local string_path="$(tmux show-environment -g TMUX_PLUGIN_MANAGER_PATH | cut -f2 -d=)"
-	# NOTE: manually expanding tilde or `$HOME` variable. Avoids using `eval` as
-	# described here http://stackoverflow.com/a/5748307/777337
-	SHARED_TPM_PATH="$(echo "$string_path" | sed "s,^\$HOME,$HOME," | sed "s,^~,$HOME,")"
-}
-
-shared_get_tpm_plugins_list() {
-	tmux show-option -gqv "$tpm_plugins_variable_name"
-}
-
-# Allowed plugin name formats:
-# 1. "git://github.com/user/plugin_name.git"
-# 2. "user/plugin_name"
-shared_plugin_name() {
-	local plugin="$1"
-	# get only the part after the last slash, e.g. "plugin_name.git"
-	local plugin_basename="$(basename "$plugin")"
-	# remove ".git" extension (if it exists) to get only "plugin_name"
-	local plugin_name="${plugin_basename%.git}"
-	echo "$plugin_name"
-}
-
-shared_plugin_path() {
-	local plugin=$1
-	local plugin_name=$(shared_plugin_name "$plugin")
-	echo "$SHARED_TPM_PATH$plugin_name/"
-}
-
-# TMUX messaging is weird. You only get a nice clean pane if you do it with
-# `run-shell` command.
-echo_message() {
-	local message="$1"
-	tmux run-shell "echo '$message'"
-}
-
-reload_tmux_environment() {
-	tmux source-file ~/.tmux.conf >/dev/null 2>&1
-}
-
-plugin_already_installed() {
-	local plugin="$1"
-	local plugin_path="$(shared_plugin_path "$plugin")"
-	cd "$plugin_path" &&
-		git remote >/dev/null 2>&1
-}
-
-end_message() {
-	echo_message ""
-	echo_message "TMUX environment reloaded."
-	echo_message ""
-	echo_message "Done, press ENTER to continue."
-}
-
-# Ensures a message is displayed for 5 seconds in tmux prompt.
-# Does not override the 'display-time' tmux option.
-display_message() {
-	local message="$1"
-
-	# display_duration defaults to 5 seconds, if not passed as an argument
-	if [ "$#" -eq 2 ]; then
-		local display_duration="$2"
-	else
-		local display_duration="5000"
-	fi
-
-	# saves user-set 'display-time' option
-	local saved_display_time=$(get_tmux_option "display-time" "750")
-
-	# sets message display time to 5 seconds
-	tmux set-option -gq display-time "$display_duration"
-
-	# displays message
-	tmux display-message "$message"
-
-	# restores original 'display-time' value
-	tmux set-option -gq display-time "$saved_display_time"
-}

scripts/source_plugins.sh

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 
 CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+HELPERS_DIR="$CURRENT_DIR/helpers"
 
-source "$CURRENT_DIR/shared_functions.sh"
+source "$HELPERS_DIR/plugin_functions.sh"
 
 plugin_dir_exists() {
 	[ -d "$1" ]
@@ -12,7 +13,7 @@ plugin_dir_exists() {
 # Files are ran as executables.
 # No errors if the plugin dir does not exist.
 silently_source_all_tmux_files() {
-	local plugin_path=$1
+	local plugin_path="$1"
 	local plugin_tmux_files="$plugin_path*.tmux"
 	if plugin_dir_exists "$plugin_path"; then
 		for tmux_file in $plugin_tmux_files; do
@@ -25,21 +26,17 @@ silently_source_all_tmux_files() {
 	fi
 }
 
-source_plugin() {
-	local plugin=$1
-	local plugin_path=$(shared_plugin_path "$plugin")
-	silently_source_all_tmux_files "$plugin_path"
-}
-
 source_plugins() {
-	local plugins=$(shared_get_tpm_plugins_list)
+	local plugin plugin_path
+	local plugins="$(tpm_plugins_list_helper)"
 	for plugin in $plugins; do
-		source_plugin "$plugin"
+		IFS='#' read -ra plugin <<< "$plugin"
+		plugin_path="$(plugin_path_helper "${plugin[0]}")"
+		silently_source_all_tmux_files "$plugin_path"
 	done
 }
 
 main() {
-	shared_set_tpm_path_constant
 	source_plugins
 }
 main

scripts/update_plugin.sh

@@ -1,74 +1,78 @@
 #!/usr/bin/env bash
 
+# this script handles core logic of updating plugins
+
 CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+HELPERS_DIR="$CURRENT_DIR/helpers"
 
-source "$CURRENT_DIR/shared_functions.sh"
+source "$HELPERS_DIR/plugin_functions.sh"
+source "$HELPERS_DIR/utility.sh"
 
-empty() {
-	[ -z "$1" ]
-}
+if [ "$1" == "--tmux-echo" ]; then # tmux-specific echo functions
+	source "$HELPERS_DIR/tmux_echo_functions.sh"
+else # shell output functions
+	source "$HELPERS_DIR/shell_echo_functions.sh"
+fi
 
-if_all() {
-	[ "$1" == "all" ]
-}
-
-cancel() {
-	exit 0
-}
+# from now on ignore first script argument
+shift
 
 pull_changes() {
 	local plugin="$1"
-	local plugin_path=$(shared_plugin_path "$plugin")
-	cd $plugin_path &&
-		git pull &&
-		git submodule update --init --recursive
+	local plugin_path="$(plugin_path_helper "$plugin")"
+	cd "$plugin_path" &&
+		GIT_TERMINAL_PROMPT=0 git pull &&
+		GIT_TERMINAL_PROMPT=0 git submodule update --init --recursive
 }
 
 update() {
-	local plugin="$1"
-	echo_message "Updating \"$plugin\""
-	$(pull_changes "$plugin" > /dev/null 2>&1) &&
-		echo_message "  \"$plugin\" update success" ||
-		echo_message "  \"$plugin\" update fail"
-}
-
-
-update_all() {
-	local plugins="$(shared_get_tpm_plugins_list)"
-	for plugin in $plugins; do
-		local plugin_name="$(shared_plugin_name "$plugin")"
-		# updating only installed plugins
-		if plugin_already_installed "$plugin_name"; then
-			update "$plugin_name"
-		fi
-	done
-}
-
-handle_plugin_update() {
-	local arg="$1"
-
-	if empty "$arg"; then
-		cancel
-
-	elif if_all "$arg"; then
-		echo_message "Updating all plugins!"
-		echo_message ""
-		update_all
-
-	elif plugin_already_installed "$arg"; then
-		update "$arg"
-
+	local plugin="$1" output
+	output=$(pull_changes "$plugin" 2>&1)
+	if (( $? == 0 )); then
+		echo_ok "  \"$plugin\" update success"
+		echo_ok "$(echo "$output" | sed -e 's/^/    | /')"
 	else
-		display_message "It seems this plugin is not installed: $arg"
-		cancel
+		echo_err "  \"$plugin\" update fail"
+		echo_err "$(echo "$output" | sed -e 's/^/    | /')"
 	fi
 }
 
-main() {
-	local arg="$1"
-	shared_set_tpm_path_constant
-	handle_plugin_update "$arg"
-	reload_tmux_environment
-	end_message
+update_all() {
+	echo_ok "Updating all plugins!"
+	echo_ok ""
+	local plugins="$(tpm_plugins_list_helper)"
+	for plugin in $plugins; do
+		IFS='#' read -ra plugin <<< "$plugin"
+		local plugin_name="$(plugin_name_helper "${plugin[0]}")"
+		# updating only installed plugins
+		if plugin_already_installed "$plugin_name"; then
+			update "$plugin_name" &
+		fi
+	done
+	wait
 }
-main "$1"
+
+update_plugins() {
+	local plugins="$*"
+	for plugin in $plugins; do
+		IFS='#' read -ra plugin <<< "$plugin"
+		local plugin_name="$(plugin_name_helper "${plugin[0]}")"
+		if plugin_already_installed "$plugin_name"; then
+			update "$plugin_name" &
+		else
+			echo_err "$plugin_name not installed!" &
+		fi
+	done
+	wait
+}
+
+main() {
+	ensure_tpm_path_exists
+	if [ "$1" == "all" ]; then
+		update_all
+	else
+		update_plugins "$*"
+	fi
+	exit_value_helper
+}
+main "$*"

scripts/update_plugin_prompt.sh

@@ -1,44 +0,0 @@
-#!/usr/bin/env bash
-
-# when invoked with `prefix + U` this script:
-# - shows a list of installed plugins
-# - starts a prompt to enter the name of the plugin that will be updated
-
-CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-
-source "$CURRENT_DIR/shared_functions.sh"
-
-display_plugin_update_list() {
-	local plugins="$(shared_get_tpm_plugins_list)"
-	echo_message "Installed plugins:"
-	echo_message ""
-
-	for plugin in $plugins; do
-		# displaying only installed plugins
-		if plugin_already_installed "$plugin"; then
-			local plugin_name="$(shared_plugin_name "$plugin")"
-			echo_message "  $plugin_name"
-		fi
-	done
-
-	echo_message ""
-	echo_message "Type plugin name to update it."
-	echo_message ""
-	echo_message "- \"all\" - updates all plugins"
-	echo_message "- ENTER - cancels"
-}
-
-update_plugin_prompt() {
-	tmux command-prompt -p 'plugin update:' " \
-		send-keys C-m; \
-		run-shell '$CURRENT_DIR/update_plugin.sh %1'"
-}
-
-
-main() {
-	reload_tmux_environment
-	shared_set_tpm_path_constant
-	display_plugin_update_list
-	update_plugin_prompt
-}
-main

scripts/update_plugin_prompt_handler.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+HELPERS_DIR="$CURRENT_DIR/helpers"
+
+if [ $# -eq 0 ]; then
+	exit 0
+fi
+
+source "$HELPERS_DIR/tmux_echo_functions.sh"
+source "$HELPERS_DIR/tmux_utils.sh"
+
+main() {
+	"$CURRENT_DIR/update_plugin.sh" --tmux-echo "$*"
+	reload_tmux_environment
+	end_message
+}
+main "$*"

scripts/variables.sh

@@ -0,0 +1,13 @@
+install_key_option="@tpm-install"
+default_install_key="I"
+
+update_key_option="@tpm-update"
+default_update_key="U"
+
+clean_key_option="@tpm-clean"
+default_clean_key="M-u"
+
+SUPPORTED_TMUX_VERSION="1.9"
+
+DEFAULT_TPM_ENV_VAR_NAME="TMUX_PLUGIN_MANAGER_PATH"
+DEFAULT_TPM_PATH="$HOME/.tmux/plugins/"

tests/expect_failed_plugin_download

@@ -0,0 +1,36 @@
+#!/usr/bin/env expect
+
+# disables script output
+log_user 0
+
+spawn tmux
+
+# Waiting for tmux to attach. If this is not done, next command, `send` will
+# not work properly.
+sleep 1
+
+# this is tmux prefix + I
+send "I"
+
+# cloning might take a while
+set timeout 20
+
+expect_after {
+  timeout { exit 1 }
+}
+
+expect {
+  "Installing \"non-existing-plugin\""
+}
+
+expect {
+  "\"non-existing-plugin\" download fail"
+}
+
+expect {
+  "Done, press ENTER to continue" {
+    exit 0
+  }
+}
+
+exit 1

tests/expect_successful_clean_plugins

@@ -0,0 +1,35 @@
+#!/usr/bin/env expect
+
+# disables script output
+log_user 0
+
+spawn tmux
+
+# Waiting for tmux to attach. If this is not done, next command, `send` will
+# not work properly.
+sleep 1
+
+# this is tmux prefix + alt + u
+send "u"
+
+set timeout 5
+
+expect_after {
+  timeout { exit 1 }
+}
+
+expect {
+  "Removing \"tmux-example-plugin\""
+}
+
+expect {
+  "\"tmux-example-plugin\" clean success"
+}
+
+expect {
+  "Done, press ENTER to continue." {
+    exit 0
+  }
+}
+
+exit 1

tests/expect_successful_multiple_plugins_download

@@ -0,0 +1,44 @@
+#!/usr/bin/env expect
+
+# disables script output
+log_user 0
+
+spawn tmux
+
+# Waiting for tmux to attach. If this is not done, next command, `send` will
+# not work properly.
+sleep 1
+
+# this is tmux prefix + I
+send "I"
+
+# cloning might take a while
+set timeout 15
+
+expect_after {
+  timeout { exit 1 }
+}
+
+expect {
+  "Installing \"tmux-example-plugin\""
+}
+
+expect {
+  "\"tmux-example-plugin\" download success"
+}
+
+expect {
+  "Installing \"tmux-copycat\""
+}
+
+expect {
+  "\"tmux-copycat\" download success"
+}
+
+expect {
+  "Done, press ENTER to continue." {
+    exit 0
+  }
+}
+
+exit 1

tests/expect_successful_plugin_download

@@ -15,40 +15,36 @@ send "I"
 # cloning might take a while
 set timeout 15
 
+expect_after {
+  timeout { exit 1 }
+}
+
 expect {
-  "Installing \"tmux-example-plugin\"" {
+  "Installing \"tmux-example-plugin\""
+}
 
-    expect {
-      "\"tmux-example-plugin\" download success" {
+expect {
+  "\"tmux-example-plugin\" download success"
+}
 
-        expect { "Done, press ENTER to continue" {
-            send "
"
-          }
-        }
-
-      }
-    }
-
-  }
-
-  timeout {
-    puts "Plugin installation timeout (1)";
-    exit 1
+expect {
+  "Done, press ENTER to continue" {
+    send "
"
   }
 }
 
+sleep 1
 # this is tmux prefix + I
 send "I"
 
 expect {
-  "Already installed \"tmux-example-plugin\"" {
+  "Already installed \"tmux-example-plugin\""
+}
 
-    expect { "Done, press ENTER to continue" { exit 0 } }
-
-  }
-
-  timeout {
-    puts "Plugin installation timeout (2)";
-    exit 1
+expect {
+  "Done, press ENTER to continue" {
+    exit 0
   }
 }
+
+exit 1

tests/expect_successful_update_of_a_single_plugin

@@ -12,50 +12,44 @@ sleep 1
 # this is tmux prefix + U
 send "U"
 
-set timeout 5
+set timeout 15
 
-expect {
-  "Installed plugins" {
-
-    expect {
-      "\"tmux-example-plugin\"" {
-
-        expect {
-          "\"all\" - updates all plugins" {
-
-            expect { "ENTER - cancels" }
-
-          }
-        }
-
-      }
-    }
-
-  }
-
-  timeout {
-    puts "Plugin update prompt timeout";
-    exit 1
-  }
+expect_after {
+  timeout { exit 1 }
 }
 
+expect {
+  "Installed plugins"
+}
+
+expect {
+  "tmux-example-plugin"
+}
+
+expect {
+  "\"all\" - updates all plugins"
+}
+
+expect {
+  "ENTER - cancels"
+}
+
+# wait for tmux to display prompt before sending characters
+sleep 1
 send "tmux-example-plugin\r"
 
 expect {
-  "Updating \"tmux-example-plugin\"" {
+  "Updating \"tmux-example-plugin\""
+}
 
-    expect {
-      "\"tmux-example-plugin\" update success" {
+expect {
+  "\"tmux-example-plugin\" update success"
+}
 
-        expect { "Done, press ENTER to continue." { exit 0 } }
-
-      }
-    }
-
-  }
-
-  timeout {
-    puts "Update all plugins timeout";
-    exit 1
+expect {
+  "Done, press ENTER to continue." {
+    exit 0
   }
 }
+
+exit 1

tests/expect_successful_update_of_all_plugins

@@ -14,54 +14,46 @@ send "U"
 
 set timeout 5
 
-expect {
-  "Installed plugins" {
-
-    expect {
-      "\"tmux-example-plugin\"" {
-
-        expect {
-          "\"all\" - updates all plugins" {
-
-            expect { "ENTER - cancels" }
-
-          }
-        }
-
-      }
-    }
-
-  }
-
-  timeout {
-    puts "Plugin update prompt timeout";
-    exit 1
-  }
+expect_after {
+  timeout { exit 1 }
 }
 
+expect {
+  "Installed plugins"
+}
+
+expect {
+  "tmux-example-plugin"
+}
+
+expect {
+  "\"all\" - updates all plugins"
+}
+
+expect {
+  "ENTER - cancels"
+}
+
+# wait for tmux to display prompt before sending characters
+sleep 1
 send "all\r"
 
 expect {
-  "Updating all plugins!" {
+  "Updating all plugins!"
+}
 
-    expect {
-      "Updating \"tmux-example-plugin\"" {
+expect {
+  "Updating \"tmux-example-plugin\""
+}
 
-        expect {
-          "\"tmux-example-plugin\" update success" {
+expect {
+  "\"tmux-example-plugin\" update success"
+}
 
-            expect { "Done, press ENTER to continue." { exit 0 } }
-
-          }
-        }
-
-      }
-    }
-
-  }
-
-  timeout {
-    puts "Update all plugins timeout";
-    exit 1
+expect {
+  "Done, press ENTER to continue." {
+    exit 0
   }
 }
+
+exit 1

tests/helpers.sh

@@ -1,55 +0,0 @@
-#!/usr/bin/env bash
-
-FAIL="false"
-
-set_tmux_conf_helper() {
-	> ~/.tmux.conf	# empty filename
-	while read -r line; do
-		echo $line >> ~/.tmux.conf
-	done
-}
-
-create_test_plugin_helper() {
-	local plugin_path="$HOME/.tmux/plugins/tmux_test_plugin/"
-	rm -rf $plugin_path
-	mkdir -p $plugin_path
-
-	while read -r line; do
-		echo $line >> "$plugin_path/test_plugin.tmux"
-	done
-	chmod +x "$plugin_path/test_plugin.tmux"
-}
-
-teardown_helper() {
-	rm ~/.tmux.conf
-	rm -rf ~/.tmux/
-	tmux kill-server >/dev/null 2>&1
-}
-
-check_dir_exists_helper() {
-	local dir_path=$1
-	if [ -d "$dir_path" ]; then
-		return 0
-	else
-		return 1
-	fi
-}
-
-fail_helper() {
-	local message="$1"
-	echo "$message" >&2
-	FAIL="true"
-}
-
-exit_value_helper() {
-	local fail="$1"
-	if [ "$FAIL" == "true" ]; then
-		echo "FAIL!"
-		echo
-		exit 1
-	else
-		echo "SUCCESS"
-		echo
-		exit 0
-	fi
-}

tests/helpers/tpm.sh

@@ -0,0 +1,13 @@
+check_dir_exists_helper() {
+	[ -d "$1" ]
+}
+
+# runs the scripts and asserts it has the correct output and exit code
+script_run_helper() {
+	local script="$1"
+	local expected_output="$2"
+	local expected_exit_code="${3:-0}"
+	$script 2>&1 |
+		grep "$expected_output" >/dev/null 2>&1 && # grep -q flag quits the script early
+		[ "${PIPESTATUS[0]}" -eq "$expected_exit_code" ]
+}

tests/run-tests-within-vm

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-
-# A test runner file.
-# Intended to be run from `./run-tests` script *within* a virtual machine.
-# DO NOT run it locally as it might overwrite your `.tmux.conf` (that's what it
-# does during the tests).
-
-CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-
-# running test suite is successful by default
-tests_exit_value=0
-
-set_global_exit_val_to_false() {
-	tests_exit_value=1
-}
-
-test_files() {
-	ls -1 "$CURRENT_DIR" |      # test files are in the current dir
-		grep -i '^test' |       # test file names start with 'test'
-		xargs                   # file names in one line
-}
-
-run_tests() {
-	local test_file
-	for test_file in $(test_files); do
-		echo "Running test: $test_file"
-		$CURRENT_DIR/$test_file
-
-		# handling exit value
-		local exit_value="$?"
-		if [ "$exit_value" != 0 ]; then
-			set_global_exit_val_to_false
-		fi
-	done
-}
-
-main() {
-	run_tests
-	exit "$tests_exit_value"
-}
-main

tests/test_plugin_clean.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TPM_DIR="$PWD"
+PLUGINS_DIR="$HOME/.tmux/plugins"
+
+source "$CURRENT_DIR/helpers/helpers.sh"
+source "$CURRENT_DIR/helpers/tpm.sh"
+
+manually_install_the_plugin() {
+	rm -rf "$PLUGINS_DIR"
+	mkdir -p "$PLUGINS_DIR"
+	cd "$PLUGINS_DIR"
+	git clone --quiet https://github.com/tmux-plugins/tmux-example-plugin
+}
+
+# TMUX KEY-BINDING TESTS
+
+test_plugin_uninstallation_via_tmux_key_binding() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	manually_install_the_plugin
+
+	"$CURRENT_DIR/expect_successful_clean_plugins" ||
+		fail_helper "[key-binding] clean fails"
+
+	teardown_helper
+}
+
+# SCRIPT TESTS
+
+test_plugin_uninstallation_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	manually_install_the_plugin
+
+	script_run_helper "$TPM_DIR/bin/clean_plugins" '"tmux-example-plugin" clean success' ||
+		fail_helper "[script] plugin cleaning fails"
+
+	teardown_helper
+}
+
+test_unsuccessful_plugin_uninstallation_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	manually_install_the_plugin
+	chmod 000 "$PLUGINS_DIR/tmux-example-plugin" # disable directory deletion
+
+	local expected_exit_code=1
+	script_run_helper "$TPM_DIR/bin/clean_plugins" '"tmux-example-plugin" clean fail' "$expected_exit_code" ||
+		fail_helper "[script] unsuccessful plugin cleaning doesn't fail"
+
+	chmod 755 "$PLUGINS_DIR/tmux-example-plugin" # enable directory deletion
+
+	teardown_helper
+}
+
+run_tests

tests/test_plugin_installation.sh

@@ -1,28 +1,284 @@
 #!/usr/bin/env bash
 
 CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PLUGINS_DIR="$HOME/.tmux/plugins"
+TPM_DIR="$PWD"
 
-source $CURRENT_DIR/helpers.sh
+CUSTOM_PLUGINS_DIR="$HOME/foo/plugins"
+ADDITIONAL_CONFIG_FILE_1="$HOME/.tmux/additional_config_file_1"
+ADDITIONAL_CONFIG_FILE_2="$HOME/.tmux/additional_config_file_2"
 
-test_plugin_installation() {
+source "$CURRENT_DIR/helpers/helpers.sh"
+source "$CURRENT_DIR/helpers/tpm.sh"
+
+# TMUX KEY-BINDING TESTS
+
+test_plugin_installation_via_tmux_key_binding() {
 	set_tmux_conf_helper <<- HERE
-	set -g @tpm_plugins "tmux-plugins/tmux-example-plugin"
-	run-shell "$PWD/tpm"
+	set -g mode-keys vi
+	set -g @plugin "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
 	HERE
 
-	# opens tmux and test it with `expect`
-	$CURRENT_DIR/expect_successful_plugin_download ||
-		fail_helper "Tmux plugin installation fails"
+	"$CURRENT_DIR/expect_successful_plugin_download" ||
+		fail_helper "[key-binding] plugin installation fails"
 
-	# check plugin dir exists after download
-	check_dir_exists_helper "$HOME/.tmux/plugins/tmux-example-plugin/" ||
-		fail_helper "Plugin download fails"
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[key-binding] plugin download fails"
 
 	teardown_helper
 }
 
-main() {
-	test_plugin_installation
-	exit_value_helper
+test_plugin_installation_via_tmux_key_binding_set_option() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set-option -g @plugin "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	"$CURRENT_DIR/expect_successful_plugin_download" ||
+		fail_helper "[key-binding][set-option] plugin installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[key-binding][set-option] plugin download fails"
+
+	teardown_helper
 }
-main
+
+test_plugin_installation_custom_dir_via_tmux_key_binding() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set-environment -g TMUX_PLUGIN_MANAGER_PATH '$CUSTOM_PLUGINS_DIR'
+
+	set -g @plugin "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	"$CURRENT_DIR/expect_successful_plugin_download" ||
+		fail_helper "[key-binding][custom dir] plugin installation fails"
+
+	check_dir_exists_helper "$CUSTOM_PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[key-binding][custom dir] plugin download fails"
+
+	teardown_helper
+	rm -rf "$CUSTOM_PLUGINS_DIR"
+}
+
+test_non_existing_plugin_installation_via_tmux_key_binding() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @plugin "tmux-plugins/non-existing-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	"$CURRENT_DIR/expect_failed_plugin_download" ||
+		fail_helper "[key-binding] non existing plugin installation doesn't fail"
+
+	teardown_helper
+}
+
+test_multiple_plugins_installation_via_tmux_key_binding() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @plugin "tmux-plugins/tmux-example-plugin"
+	\ \ set  -g    @plugin 'tmux-plugins/tmux-copycat'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	"$CURRENT_DIR/expect_successful_multiple_plugins_download" ||
+		fail_helper "[key-binding] multiple plugins installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[key-binding] plugin download fails (tmux-example-plugin)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-copycat/" ||
+		fail_helper "[key-binding] plugin download fails (tmux-copycat)"
+
+	teardown_helper
+}
+
+test_plugins_installation_from_sourced_file_via_tmux_key_binding() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	source '$ADDITIONAL_CONFIG_FILE_1'
+	set -g @plugin 'tmux-plugins/tmux-example-plugin'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	mkdir ~/.tmux
+	echo "set -g @plugin 'tmux-plugins/tmux-copycat'" > "$ADDITIONAL_CONFIG_FILE_1"
+
+	"$CURRENT_DIR/expect_successful_multiple_plugins_download" ||
+		fail_helper "[key-binding][sourced file] plugins installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[key-binding][sourced file] plugin download fails (tmux-example-plugin)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-copycat/" ||
+		fail_helper "[key-binding][sourced file] plugin download fails (tmux-copycat)"
+
+	teardown_helper
+}
+
+test_plugins_installation_from_multiple_sourced_files_via_tmux_key_binding() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	\ \ source    '$ADDITIONAL_CONFIG_FILE_1'
+	source-file '$ADDITIONAL_CONFIG_FILE_2'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	mkdir ~/.tmux
+	echo "set -g @plugin 'tmux-plugins/tmux-example-plugin'" > "$ADDITIONAL_CONFIG_FILE_1"
+	echo "  set -g @plugin 'tmux-plugins/tmux-copycat'" > "$ADDITIONAL_CONFIG_FILE_2"
+
+	"$CURRENT_DIR/expect_successful_multiple_plugins_download" ||
+		fail_helper "[key-binding][multiple sourced files] plugins installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[key-binding][multiple sourced files] plugin download fails (tmux-example-plugin)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-copycat/" ||
+		fail_helper "[key-binding][multiple sourced files] plugin download fails (tmux-copycat)"
+
+	teardown_helper
+}
+
+# SCRIPT TESTS
+
+test_plugin_installation_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @plugin "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" '"tmux-example-plugin" download success' ||
+		fail_helper "[script] plugin installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[script] plugin download fails"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" 'Already installed "tmux-example-plugin"' ||
+		fail_helper "[script] plugin already installed message fail"
+
+	teardown_helper
+}
+
+test_plugin_installation_custom_dir_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set-environment -g TMUX_PLUGIN_MANAGER_PATH '$CUSTOM_PLUGINS_DIR'
+
+	set -g @plugin "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" '"tmux-example-plugin" download success' ||
+		fail_helper "[script][custom dir] plugin installation fails"
+
+	check_dir_exists_helper "$CUSTOM_PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[script][custom dir] plugin download fails"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" 'Already installed "tmux-example-plugin"' ||
+		fail_helper "[script][custom dir] plugin already installed message fail"
+
+	teardown_helper
+	rm -rf "$CUSTOM_PLUGINS_DIR"
+}
+
+test_non_existing_plugin_installation_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @plugin "tmux-plugins/non-existing-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	local expected_exit_code=1
+	script_run_helper "$TPM_DIR/bin/install_plugins" '"non-existing-plugin" download fail' "$expected_exit_code" ||
+		fail_helper "[script] non existing plugin installation doesn't fail"
+
+	teardown_helper
+}
+
+test_multiple_plugins_installation_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @plugin "tmux-plugins/tmux-example-plugin"
+	\ \ set  -g    @plugin 'tmux-plugins/tmux-copycat'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" '"tmux-example-plugin" download success' ||
+		fail_helper "[script] multiple plugins installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[script] plugin download fails (tmux-example-plugin)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-copycat/" ||
+		fail_helper "[script] plugin download fails (tmux-copycat)"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" 'Already installed "tmux-copycat"' ||
+		fail_helper "[script] multiple plugins already installed message fail"
+
+	teardown_helper
+}
+
+test_plugins_installation_from_sourced_file_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	source '$ADDITIONAL_CONFIG_FILE_1'
+	set -g @plugin 'tmux-plugins/tmux-example-plugin'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	mkdir ~/.tmux
+	echo "set -g @plugin 'tmux-plugins/tmux-copycat'" > "$ADDITIONAL_CONFIG_FILE_1"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" '"tmux-copycat" download success' ||
+		fail_helper "[script][sourced file] plugins installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[script][sourced file] plugin download fails (tmux-example-plugin)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-copycat/" ||
+		fail_helper "[script][sourced file] plugin download fails (tmux-copycat)"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" 'Already installed "tmux-copycat"' ||
+		fail_helper "[script][sourced file] plugins already installed message fail"
+
+	teardown_helper
+}
+
+test_plugins_installation_from_multiple_sourced_files_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	\ \ source    '$ADDITIONAL_CONFIG_FILE_1'
+	source-file '$ADDITIONAL_CONFIG_FILE_2'
+	set -g @plugin 'tmux-plugins/tmux-example-plugin'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	mkdir ~/.tmux
+	echo " set   -g @plugin 'tmux-plugins/tmux-copycat'" > "$ADDITIONAL_CONFIG_FILE_1"
+	echo "set -g @plugin 'tmux-plugins/tmux-sensible'" > "$ADDITIONAL_CONFIG_FILE_2"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" '"tmux-sensible" download success' ||
+		fail_helper "[script][multiple sourced files] plugins installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[script][multiple sourced files] plugin download fails (tmux-example-plugin)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-copycat/" ||
+		fail_helper "[script][multiple sourced files] plugin download fails (tmux-copycat)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-sensible/" ||
+		fail_helper "[script][multiple sourced files] plugin download fails (tmux-sensible)"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" 'Already installed "tmux-sensible"' ||
+		fail_helper "[script][multiple sourced files] plugins already installed message fail"
+
+	teardown_helper
+}
+
+run_tests

tests/test_plugin_installation_legacy.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PLUGINS_DIR="$HOME/.tmux/plugins"
+TPM_DIR="$PWD"
+
+source "$CURRENT_DIR/helpers/helpers.sh"
+source "$CURRENT_DIR/helpers/tpm.sh"
+
+# TMUX KEY-BINDING TESTS
+
+test_plugin_installation_via_tmux_key_binding() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @tpm_plugins "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	# opens tmux and test it with `expect`
+	$CURRENT_DIR/expect_successful_plugin_download ||
+		fail_helper "[key-binding] plugin installation fails"
+
+	# check plugin dir exists after download
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[key-binding] plugin download fails"
+
+	teardown_helper
+}
+
+test_legacy_and_new_syntax_for_plugin_installation_work_via_tmux_key_binding() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @tpm_plugins "                   \
+		tmux-plugins/tmux-example-plugin    \
+	"
+	set -g @plugin 'tmux-plugins/tmux-copycat'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	# opens tmux and test it with `expect`
+	"$CURRENT_DIR"/expect_successful_multiple_plugins_download ||
+		fail_helper "[key-binding] multiple plugins installation fails"
+
+	# check plugin dir exists after download
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[key-binding] plugin download fails (tmux-example-plugin)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-copycat/" ||
+		fail_helper "[key-binding] plugin download fails (tmux-copycat)"
+
+	teardown_helper
+}
+
+# SCRIPT TESTS
+
+test_plugin_installation_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @tpm_plugins "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" '"tmux-example-plugin" download success' ||
+		fail_helper "[script] plugin installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[script] plugin download fails"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" 'Already installed "tmux-example-plugin"' ||
+		fail_helper "[script] plugin already installed message fail"
+
+	teardown_helper
+}
+
+test_legacy_and_new_syntax_for_plugin_installation_work_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @tpm_plugins "                   \
+		tmux-plugins/tmux-example-plugin    \
+	"
+	set -g @plugin 'tmux-plugins/tmux-copycat'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" '"tmux-example-plugin" download success' ||
+		fail_helper "[script] multiple plugin installation fails"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-example-plugin/" ||
+		fail_helper "[script] plugin download fails (tmux-example-plugin)"
+
+	check_dir_exists_helper "$PLUGINS_DIR/tmux-copycat/" ||
+		fail_helper "[script] plugin download fails (tmux-copycat)"
+
+	script_run_helper "$TPM_DIR/bin/install_plugins" 'Already installed "tmux-copycat"' ||
+		fail_helper "[script] multiple plugins already installed message fail"
+
+	teardown_helper
+}
+
+run_tests

tests/test_plugin_sourcing.sh

@@ -1,18 +1,41 @@
 #!/usr/bin/env bash
 
 CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TPM_DIR="$PWD"
+PLUGINS_DIR="$HOME/.tmux/plugins"
 
-source $CURRENT_DIR/helpers.sh
+CUSTOM_PLUGINS_DIR="$HOME/foo/plugins"
+
+source "$CURRENT_DIR/helpers/helpers.sh"
+source "$CURRENT_DIR/helpers/tpm.sh"
 
 check_binding_defined() {
 	local binding="$1"
 	tmux list-keys | grep -q "$binding"
 }
 
+create_test_plugin_helper() {
+	local plugin_path="$PLUGINS_DIR/tmux_test_plugin/"
+	rm -rf "$plugin_path"
+	mkdir -p "$plugin_path"
+
+	while read line; do
+		echo "$line" >> "$plugin_path/test_plugin.tmux"
+	done
+	chmod +x "$plugin_path/test_plugin.tmux"
+}
+
+check_tpm_path() {
+	local correct_tpm_path="$1"
+	local tpm_path="$(tmux start-server\; show-environment -g TMUX_PLUGIN_MANAGER_PATH | cut -f2 -d=)"
+	[ "$correct_tpm_path" == "$tpm_path" ]
+}
+
 test_plugin_sourcing() {
 	set_tmux_conf_helper <<- HERE
-	set -g @tpm_plugins "doesnt_matter/tmux_test_plugin"
-	run-shell "$PWD/tpm"
+	set -g mode-keys vi
+	set -g @plugin "doesnt_matter/tmux_test_plugin"
+	run-shell "$TPM_DIR/tpm"
 	HERE
 
 	# manually creates a local tmux plugin
@@ -27,8 +50,29 @@ test_plugin_sourcing() {
 	teardown_helper
 }
 
-main() {
-	test_plugin_sourcing
-	exit_value_helper
+test_default_tpm_path() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	check_tpm_path "${PLUGINS_DIR}/" ||
+		fail_helper "Default TPM path not correct"
+
+	teardown_helper
 }
-main
+
+test_custom_tpm_path() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set-environment -g TMUX_PLUGIN_MANAGER_PATH '$CUSTOM_PLUGINS_DIR'
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	check_tpm_path "$CUSTOM_PLUGINS_DIR" ||
+		fail_helper "Custom TPM path not correct"
+
+	teardown_helper
+}
+
+run_tests

tests/test_plugin_update.sh

@@ -1,35 +1,60 @@
 #!/usr/bin/env bash
 
 CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TPM_DIR="$PWD"
+PLUGINS_DIR="$HOME/.tmux/plugins"
 
-source $CURRENT_DIR/helpers.sh
+source "$CURRENT_DIR/helpers/helpers.sh"
+source "$CURRENT_DIR/helpers/tpm.sh"
 
 manually_install_the_plugin() {
-	mkdir -p ~/.tmux/plugins/
-	cd ~/.tmux/plugins/
+	mkdir -p "$PLUGINS_DIR"
+	cd "$PLUGINS_DIR"
 	git clone --quiet https://github.com/tmux-plugins/tmux-example-plugin
 }
 
-test_plugin_installation() {
+# TMUX KEY-BINDING TESTS
+
+test_plugin_update_via_tmux_key_binding() {
 	set_tmux_conf_helper <<- HERE
-	set -g @tpm_plugins "tmux-plugins/tmux-example-plugin"
-	run-shell "$PWD/tpm"
+	set -g mode-keys vi
+	set -g @plugin "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
 	HERE
 
 	manually_install_the_plugin
 
-	# opens tmux and test it with `expect`
-	$CURRENT_DIR/expect_successful_update_of_all_plugins ||
-		fail_helper "Tmux 'update all plugins' fails"
+	"$CURRENT_DIR/expect_successful_update_of_all_plugins" ||
+		fail_helper "[key-binding] 'update all plugins' fails"
 
-	$CURRENT_DIR/expect_successful_update_of_a_single_plugin ||
-		fail_helper "Tmux 'update single plugin' fails"
+	"$CURRENT_DIR/expect_successful_update_of_a_single_plugin" ||
+		fail_helper "[key-binding] 'update single plugin' fails"
 
 	teardown_helper
 }
 
-main() {
-	test_plugin_installation
-	exit_value_helper
+# SCRIPT TESTS
+
+test_plugin_update_via_script() {
+	set_tmux_conf_helper <<- HERE
+	set -g mode-keys vi
+	set -g @plugin "tmux-plugins/tmux-example-plugin"
+	run-shell "$TPM_DIR/tpm"
+	HERE
+
+	manually_install_the_plugin
+
+	local expected_exit_code=1
+	script_run_helper "$TPM_DIR/bin/update_plugins" 'usage' "$expected_exit_code" ||
+		fail_helper "[script] running update plugins without args should fail"
+
+	script_run_helper "$TPM_DIR/bin/update_plugins tmux-example-plugin" '"tmux-example-plugin" update success' ||
+		fail_helper "[script] plugin update fails"
+
+	script_run_helper "$TPM_DIR/bin/update_plugins all" '"tmux-example-plugin" update success' ||
+		fail_helper "[script] update all plugins fails"
+
+	teardown_helper
 }
-main
+
+run_tests

tpm

@@ -1,43 +1,80 @@
 #!/usr/bin/env bash
 
 CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+BINDINGS_DIR="$CURRENT_DIR/bindings"
+SCRIPTS_DIR="$CURRENT_DIR/scripts"
 
-SUPPORTED_TMUX_VERSION="1.9"
+source "$SCRIPTS_DIR/variables.sh"
+
+get_tmux_option() {
+	local option="$1"
+	local default_value="$2"
+	local option_value="$(tmux show-option -gqv "$option")"
+	if [ -z "$option_value" ]; then
+		echo "$default_value"
+	else
+		echo "$option_value"
+	fi
+}
+
+tpm_path_set() {
+	tmux show-environment -g "$DEFAULT_TPM_ENV_VAR_NAME" >/dev/null 2>&1
+}
+
+# Check if configuration file exists at an XDG-compatible location, if so use
+# that directory for TMUX_PLUGIN_MANAGER_PATH. Otherwise use $DEFAULT_TPM_PATH.
+set_default_tpm_path() {
+	local xdg_tmux_path="${XDG_CONFIG_HOME:-$HOME/.config}/tmux"
+	local tpm_path="$DEFAULT_TPM_PATH"
+
+	if [ -f "$xdg_tmux_path/tmux.conf" ]; then
+		tpm_path="$xdg_tmux_path/plugins/"
+	fi
+
+	tmux set-environment -g "$DEFAULT_TPM_ENV_VAR_NAME" "$tpm_path"
+}
 
 # Ensures TMUX_PLUGIN_MANAGER_PATH global env variable is set.
-# Default tpm path is "$HOME/.tmux/plugins/". That's where all the plugins are
-# downloaded.
 #
 # Put this in `.tmux.conf` to override the default:
 # `set-environment -g TMUX_PLUGIN_MANAGER_PATH "/some/other/path/"`
 set_tpm_path() {
-	$CURRENT_DIR/scripts/set_tpm_path.sh >/dev/null 2>&1
+	if ! tpm_path_set; then
+		set_default_tpm_path
+	fi
 }
 
-# 1. Fetches plugin names from `@tpm_plugins` user variable.
+# 1. Fetches plugin names from `@plugin` variables
 # 2. Creates full plugin path
 # 3. Sources all *.tmux files from each of the plugin directories
 #	 - no errors raised if directory does not exist
 # Files are sourced as tmux config files, not as shell scripts!
 source_plugins() {
-	$CURRENT_DIR/scripts/source_plugins.sh >/dev/null 2>&1
+	"$SCRIPTS_DIR/source_plugins.sh" >/dev/null 2>&1
 }
 
-# Defines key binding:
-# prefix + I - downloads TPM plugins and reloads TMUX environment.
-set_tpm_key_binding() {
-	tmux bind-key I run-shell "$CURRENT_DIR/scripts/install_plugins.sh >/dev/null 2>&1"
-	tmux bind-key U run-shell "$CURRENT_DIR/scripts/update_plugin_prompt.sh"
+# prefix + I - downloads TPM plugins and reloads TMUX environment
+# prefix + U - updates a plugin (or all of them) and reloads TMUX environment
+# prefix + alt + u - remove unused TPM plugins and reloads TMUX environment
+set_tpm_key_bindings() {
+	local install_key="$(get_tmux_option "$install_key_option" "$default_install_key")"
+	tmux bind-key "$install_key" run-shell "$BINDINGS_DIR/install_plugins"
+
+	local update_key="$(get_tmux_option "$update_key_option" "$default_update_key")"
+	tmux bind-key "$update_key" run-shell "$BINDINGS_DIR/update_plugins"
+
+	local clean_key="$(get_tmux_option "$clean_key_option" "$default_clean_key")"
+	tmux bind-key "$clean_key" run-shell "$BINDINGS_DIR/clean_plugins"
 }
 
 supported_tmux_version_ok() {
-	$CURRENT_DIR/scripts/check_tmux_version.sh "$SUPPORTED_TMUX_VERSION"
+	"$SCRIPTS_DIR/check_tmux_version.sh" "$SUPPORTED_TMUX_VERSION"
 }
 
 main() {
 	if supported_tmux_version_ok; then
 		set_tpm_path
-		set_tpm_key_binding
+		set_tpm_key_bindings
 		source_plugins
 	fi
 }

vagrant_provisioning.sh

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-
-sudo apt-get update
-sudo apt-get install -y git-core expect python-software-properties software-properties-common
-
-# install latest Tmux 1.9a
-sudo add-apt-repository -y ppa:pi-rho/dev
-sudo apt-get update
-sudo apt-get install -y tmux=1.9a-1~ppa1~p