Merge pull request #501 from Masterminds/docs/plugins
Updating the plugins documentation and adding listing
diff --git a/docs/plugins.md b/docs/plugins.md
index 98f24ae..bc3b596 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -1,44 +1,47 @@
# Glide Plugins
-(Not to be confused with Glade Plugins. Pew.)
+Glide supports a simple plugin system similar to Git.
-Glide supports a simple plugin system similar to Git. When Glide
-encounters a subcommand that it does not know, it will try to delegate
-it to another executable according to the following rules.
+## Existing Plugins
+
+Some plugins exist today for Glide including:
+
+* [glide-vc](https://github.com/sgotti/glide-vc) - The vendor cleaner allows you to strip files files not needed for building your application from the `vendor/` directory.
+* [glide-brew](https://github.com/heewa/glide-brew) - Convert Go deps managed by glide to Homebrew resources to help you make brew formulas for you Go programs.
+* [glide-hash](https://github.com/mattfarina/glide-hash) - Generates a hash of the `glide.yaml` file compatible with Glides internal hash.
+
+_Note, to add plugins to this list please create a pull request._
+
+## How Plugins Work
+
+When Glide encounters a subcommand that it does not know, it will try to delegate it to another executable according to the following rules.
Example:
```
-$ glide in # We know this command, so we execute it
-$ glide foo # We don't know this command, so we look for a suitable
- # plugin.
+$ glide install # We know this command, so we execute it
+$ glide foo # We don't know this command, so we look for a suitable
+ # plugin.
```
-In the example above, when glide receives the command `foo`, which it
-does not know, it will do the following:
+In the example above, when glide receives the command `foo`, which it does not know, it will do the following:
1. Transform the name from `foo` to `glide-foo`
-2. Look on the system `$PATH` for `glide-foo`. If it finds a program by
- that name, execute it...
-3. Or else, look at the current project's root for `glide-foo`. (That
- is, look in the same directory as glide.yaml). If found, execute it.
+2. Look on the system `$PATH` for `glide-foo`. If it finds a program by that name, execute it...
+3. Or else, look at the current project's root for `glide-foo`. (That is, look in the same directory as `glide.yaml`). If found, execute it.
4. If no suitable command is found, exit with an error.
## Writing a Glide Plugin
-A Glide plugin can be written in any language you wish, provided that it
-can be executed from the command line as a subprocess of Glide. The
-example included with Glide is a simple Bash script. We could just as
-easily write Go, Python, Perl, or even Java code (with a wrapper) to
+A Glide plugin can be written in any language you wish, provided that it can be executed from the command line as a subprocess of Glide. The example included with Glide is a simple Bash script. We could just as easily write Go, Python, Perl, or even Java code (with a wrapper) to
execute.
A glide plugin must be in one of two locations:
-1. Somewhere on the PATH (including `$GLIDE_PATH/_vendor/bin`)
+1. Somewhere on the PATH
2. In the same directory as `glide.yaml`
-It is recommended that system-wide Glide plugins go in `/usr/local/bin`
-while project-specific plugins go in the same directory as `glide.yaml`.
+It is recommended that system-wide Glide plugins go in `/usr/local/bin` or `$GOPATH/bin` while project-specific plugins go in the same directory as `glide.yaml`.
### Arguments and Flags
@@ -48,32 +51,15 @@
$ glide foo -name=Matt myfile.txt
```
-Glide will interpret this as a request to execute `glide-foo` with the
-arguments `-name=Matt myfile.txt`. It will not attempt to interpret
-those arguments or modify them in any way.
+Glide will interpret this as a request to execute `glide-foo` with the arguments `-name=Matt myfile.txt`. It will not attempt to interpret those arguments or modify them in any way.
-Hypothetically, if Glide had a `-x` flag of its own, you could call
-this:
+Hypothetically, if Glide had a `-x` flag of its own, you could call this:
```
$ glide -x foo -name=Matt myfile.txt
```
-In this case, glide would interpret and swollow the -x and pass the rest
-on to glide-foo as in the example above.
-
-### Environment Variables
-
-When Glide executes a plugin, it passes through all of its environment
-variables, including...
-
-- GOPATH: Gopath
-- PATH: Executable paths
-- GLIDE_GOPATH: Gopath (in case GOPATH gets overridden by another
- script)
-- GLIDE_PROJECT: The path to the project
-- GLIDE_YAML: The path to the project's YAML
-- ALREADY_GLIDING: 1 if we are in a `glide in` session.
+In this case, glide would interpret and swollow the -x and pass the rest on to `glide-foo` as in the example above.
## Example Plugin
@@ -84,5 +70,3 @@
echo "Hello"
```
-
-Yup, that's it. Also see `glide-example-plugin` for a bigger example.
diff --git a/mkdocs.yml b/mkdocs.yml
index 29109e0..6d6764b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,5 +8,6 @@
- Commands: commands.md
- Resolving Imports: resolving-imports.md
- Vendor Directories: vendor.md
+- Plugins: plugins.md
- F.A.Q.: faq.md
theme: readthedocs
