Adding tpm

5 files changed, 250 insertions, 0 deletions

diff --git a/plugins/tpm/docs/automatic_tpm_installation.md b/plugins/tpm/docs/automatic_tpm_installation.md
new file mode 100644
index 0000000..630573f
--- /dev/null
+++ b/plugins/tpm/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.
diff --git a/plugins/tpm/docs/changing_plugins_install_dir.md b/plugins/tpm/docs/changing_plugins_install_dir.md
new file mode 100644
index 0000000..93af675
--- /dev/null
+++ b/plugins/tpm/docs/changing_plugins_install_dir.md
@@ -0,0 +1,14 @@
+# Changing plugins install dir
+
+By default, TPM installs plugins to `~/.tmux/plugins/`.
+
+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`.
diff --git a/plugins/tpm/docs/how_to_create_plugin.md b/plugins/tpm/docs/how_to_create_plugin.md
new file mode 100644
index 0000000..b1a68f9
--- /dev/null
+++ b/plugins/tpm/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.
diff --git a/plugins/tpm/docs/managing_plugins_via_cmd_line.md b/plugins/tpm/docs/managing_plugins_via_cmd_line.md
new file mode 100644
index 0000000..7aefd7d
--- /dev/null
+++ b/plugins/tpm/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
diff --git a/plugins/tpm/docs/tpm_not_working.md b/plugins/tpm/docs/tpm_not_working.md
new file mode 100644
index 0000000..87d2998
--- /dev/null
+++ b/plugins/tpm/docs/tpm_not_working.md
@@ -0,0 +1,80 @@
+# 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
+```