script/plugin - The Missing Manual Written By: Ben Wyrosdick January 21st, 2007

It is frustrating, as a new an unseasoned rails developer, that there is sometimes documentation adnouseum about topics that you already know (please do not tell us one more time about how a scaffold works) and how little documentation is out there about some of the lesser known more powerful features (plugins for instance). I can find lots of documentation on installing a plugin, but then what? What if a newer version of that plugin is available or if I decide I don’t want that plugin anymore? Why isn’t that information easily accessible, believe me I have looked. I have the second edition of the Agile Web Development with Rails book and I have looked all over their wiki … nothing that I could find (Doesn’t mean it isn’t there … it just means it isn’t easy to find)

So here we go with the missing manual for the script/plugin command

This will cover the functionality in the recently released rails version 1.2.1. If you are still using version 1.1.6 the only difference will be that you don’t have the ‘info’ command

Since I had a hard time finding documentation I went to the script/plugin itself …

script/plugin -h

I ran the standard help function and found what I was looking for. Well, I thought I did. After some digging under the covers I found one key function that wasn’t acting like expected, but I will save that till a little later. Here is what I got back from the previous command.

Usage: plugin [OPTIONS] command
Rails plugin manager.

GENERAL OPTIONS
  -r, --root=DIR                   Set an explicit rails app directory.
                                  Default: /Users/bwyrosdick/rails/wob
  -s, --source=URL1,URL2           Use the specified plugin repositories instead of the defaults.
  -v, --verbose                    Turn on verbose output.
  -h, --help                       Show this help message.

COMMANDS
  discover   Discover plugin repositories.
  list       List available plugins.
  install    Install plugin(s) from known repositories or URLs.
  update     Update installed plugins.
  remove     Uninstall plugins.
  source     Add a plugin source repository.
  unsource   Remove a plugin repository.
  sources    List currently configured plugin repositories.

EXAMPLES
  Install a plugin:
    plugin install continuous_builder

  Install a plugin from a subversion URL:
    plugin install http://dev.rubyonrails.com/svn/rails/plugins/continuous_builder

  Install a plugin and add a svn:externals entry to vendor/plugins
    plugin install -x continuous_builder

  List all available plugins:
    plugin list

  List plugins in the specified repository:
    plugin list --source=http://dev.rubyonrails.com/svn/rails/plugins/

  Discover and prompt to add new repositories:
    plugin discover

  Discover new repositories but just list them, don't add anything:
    plugin discover -l

  Add a new repository to the source list:
    plugin source http://dev.rubyonrails.com/svn/rails/plugins/

  Remove a repository from the source list:
    plugin unsource http://dev.rubyonrails.com/svn/rails/plugins/

  Show currently configured repositories:
    plugin sources

This is also the screen that you get if you run it from rails version 1.1.6 so I am not sure if they left out a command on purpose but the 1.2.1 version will also take a command named ‘info’. It returns the about.yml for that plugin. Since this is the “missing manual” I won’t go into any detail on the more documented features of the script/plugin command. I will focus on plugin management.

Installing Plugin

Installation is very easy for plugins. If you use the plugin repositories all you have to do is type

script/plugin install {name}

if you don’t use the repositories or you want to explicitly get a certain version of a plugin from source control use

script/plugin install {url}

Removing Plugin

Removing, or uninstalling, a plugin is just as simple

script/plugin remove {name}

Updating Plugin

Finally we get to the part that I told you doesn’t act the way it is supposed to. The rails documentation says that update will “Update installed plugins.” Mostly, it is simply a wrapper for the “svn up” command. The propper syntax is …

script/plugin update {name}

If you have your code checked into svn then the code simply takes the {name} and runs the following command …

svn up {name}

This does very little to update the plugin since when we run the ‘install’ command we run an export on the original repository and will check the code into our own repository. So when this ‘update’ command is run it goes out to your repository and gets an update from there, which shouldn’t have any changes on it. There are a few exceptions. That is that you can install a plugin using an SVN hook or you could have a plugin that you created inside of that project with ‘script/generate plugin {name}’

First we will look into the SVN hooks. There are two options available. You can checkout the plugin using the -o option, or use svn:externals with the -x option. if you use -o then the plugin won’t be deployed to a remote server unless you copy it manually, so this isn’t a great alternative. Using externals is the better choice but it has some draw backs as well. It means that you are adding a dependancy to that repository in your project and you will have trouble deploying if that repository becomes unavailable. This isn’t a problem if the plugin is one that you created and manage but it can be if you are relying on a 3rd party. To install via externals use the following syntax …

script/plugin install -x {name/url}

Now when you run the update command it will go check in the repository that you installed the plugin from for updates.

If you really want to update a plugin, that isn’t a plugin you created inside of that project and isn’t connected via externals, to a newer version then you need to remove it then reinstall it, or just do a force install. Like so …

script/plugin remove {name}
script/plugin install {name/url}

or …

script/plugin install -f {name/url}

If you have your code checked into source control you need to go ahead and commit changes after each command or you are likely to get things out of sync, especially with SVN.