script/plugin - The Missing Manual
Posted by ben, Sun Jan 21 12:14:00 UTC 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.